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Preface 


Preface 


Volume 2: The SOS Calls comprises the remaining chapters and the 
appendixes of this manual. The chapter numbers continue the sequence 
of those in Volume 1. 


Volume 2 defines the individual SOS calls. Chapter 9 contains a 
description of each file call; Chapter 10, each device call; Chapter 11, each 
memory call; and Chapter 12, each utility call. Each of these chapters is 
divided into two sections: calls, and errors. 


The calls defined in each chapter are arranged in numerical order by call 
number (for example, CREATE is $C@). Each call description contains the 
following information: 


e Definition of the call 
e Required parameters 
e Optional parameters 
e Comments 

e Errors 


The parameter fields are of four types: 


Pointer (2 bytes): The location of a table or parameter list. 

Value (1, 2, or 4 bytes): A parameter passed by the caller to SOS. 
Result (1, 2, or 4 bytes): A parameter returned by SOS to 

the caller. 

Value/result (1, 2, or 4 bytes): A parameter passed to SOS and 
back to the caller, possibly changed. 

Unused (any length): Occurs when the same parameter list is 
used by two calls, one of which ignores some parameters in the 
list. An unused field can be of any length. 
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= 
Each SOS call has three parts, described in Chapter 8 of Volume 1: 
baad 
e The call block 
e The required parameter list — 
e The optional parameter list LJ 
They can be diagrammed as shown in Figure 0-1: = 
; = 
1 = 
2 Lad 
parm list 
pointer 
3 bas 
= 
0 parm_count = $03 
value 
— 
1 
pathname 
9 pointer —_ 
3 = 
option list 
pointer 
4 —_ 
: Lj 
; file type = 
value 
1 — 
aux_type 
value | 
2 — 
3 stor_type | 
value Iau 


Figure 0-1. Parts of the SOS Call 


Preface 


Each call description is accompanied by a diagram like that shown in 


A Figure 0-1. Most of the diagrams omit the call block, as these are identical, 
a except for the call_ num , and show only the required and optional 

; parameter lists. In addition, the parm_count (shown in the diagram) is 
— omitted from the required parameter list. 


The one exception to this pattern is TERMINATE, for which the call block 
Py only is shown, as in Figure 0-2, because it differs from the standard form. 
= See section 12.1.6 for details. 


call_num = $65 
value 


a 


parm_list = p 
pointer 


- Figure 0-2. TERMINATE Call Block 
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File Calls and Errors 


9.1 File Calls 
9.1.1 CREATE 
9.1.2 DESTROY 
9.1.3 RENAME 
9.1.4 SET FILE INFO 
9.1.5 GET _FILE_INFO 
9.1.6 VOLUME 
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9.1.17 SET EOF 
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9.1.19 SET LEVEL 
9.1.20 GET LEVEL 

9.2 File Calls Errors 


File Calls and Errors 
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9.1 File Calls 

This section contains descriptions of all calls that operate on files. These ' 

calls operate on closed files and refer to a file by its pathname. — 
$C: CREATE = 
$C1: DESTROY | 
$C2: RENAME _ 
$C3: SET FILE INFO } 
$C4: GET FILE INFO _ 
$C5: VOLUME | 
$C6: SET PREFIX = 
$C7: GET PREFIX | 
$C8: OPEN _ 

These calls operate on access paths to open files and refer to the access _ 

path by its ref_num, returned by the OPEN call. 
$C9: NEWLINE 
$CA: READ = 
$CB: WRITE | 
$CC: CLOSE —_ 
$CD: FLUSH , 
$CE: SET MARK = 
$CF: GET MARK | 
$D@: SET EOF _— 
$01: GET EOF ) 
,D2: SET LEVEL _ 
$D3: GET_LEVEL | 

—_ 
head 
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— 9.1.1. CREATE File Call $C 
ome This call creates a standard file or CREATE $C@ 
) subdirectory file on a volume mounted 
ome on a block device. A directory 
entry is established, and at least one , 
— block is allocated on the volume. pathname 
| pointer 
_— This call cannot create a volume directory 
| or acharacter file. Volume directories 3 a 
a are “created” by the formatting i rile 
) utility on the Apple III Utilities disk. 4 . 
— Character files are created” by the 
i System Configuration Program. 5 
ze | 
Required Parameter List ‘ 
a | value 
pathname: pointer 1 
ry ' aux_type 
| This parameter is a pointer toa ‘ value 
_ string in memory containing the 
pathname of the file to be created: ; 
—_ the first byte of the string contains value 
| the number of bytes in the , 
aaa pathname; the remaining bytes 
| contain the pathname itself. The : 
_ last name in the pathname should EOF 
} be that of a file that does not 7 valle 
_— currently exist in the specified 
) directory, or a DUPERR will result. 7 


option list: pointer 


a | This is a pointer to the optional parameter list if length (below) is between 
1 and 8; otherwise it is ignored. 


length: 1 byte value 
— Range: $0..$08 


This is the length in bytes of the optional parameter list. It specifies which 
optional parameters are supplied. 
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The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take half 
a parameter, but reduces the length to the next defined value. 


® = no optional parameters 

1 = file_type 

3 = file_type through aux_type 
4 = file_type through stor_type 
8 = file_type through EOF 


Optional Parameter List 


file_type: 1 byte value 
Range: $00..$FF 
Default: $00 


This is the type identifier for this file. The file_type does not affect the 
way in which SOS deals with the file: it is used only by interpreters to 
determine the internal arrangement and meaning of the bytes in the file. 
These values of file_type are now defined: 


$00 = Typeless file (BASIC or Pascal "unknown file) 
$01 = File containing all bad blocks on the volume 
$62 = Pascal or assembly-language code file 

$03 = Pascal text file 

$04 = BASIC text file; Pascal ASCII file 

$05 = Pascal data file 

$06 = General binary file 

$07 = Font file 

$08 = Screen image file 

$09 = Business BASIC program file 

$OA = Business BASIC data file 

$0B = Word Processor file 

$0C = SOSsystem file (DRIVER, INTERP, KERNEL) 
$0D, $0E = SOS reserved 

$OF = Directory file (see storage_type) 


$10..$DF = SOS reserved 
$EQ@..$FF = ProDOS reserved 
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aux_type: 2 byte value 
Range: $00..$FFFF 
Default: $0000 


This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field 
to store the record size of its data files. If the file is a volume directory 
(storage_type is $0F), these bytes contain the total number of blocks on 
the volume. 


siorage_type: 1 byte value 
Range: $01..$9D 
Default: $01 


This indicates whether the file is to be a standard file ($01) ora 
subdirectory file ($2D). All other values are illegal and will result in a 
TYPERR. 


EOF: 4 byte value 
Range: $00900000..S$60FFFFFF 
Default: $00000000 


This specifies the amount of space to preallocate for the file.One data 
block is automatically allocated regardless of the value of EOF; additional 
data blocks are allocated until the number of bytes in the allocated data 
blocks equals or exceeds EOF. In addition to the data blocks, index blocks 
are allocated as necessary. 


The maximum creation size for standard files is $0OFFFFFF, or $8000 
blocks. The maximum creation size for subdirectories is $@@@@FFFF, or 
$80 blocks. The total number of blocks occupied by a file is the number of 
data blocks plus the number of index blocks: see Chapter 5 of Volume 1 
for more information. 


Comments 


The file created must be a block file. The access attribute of the file is 
implicitly set to the following: 


standard file = $E3: (destroy, backup, rename, write, read) 
subdirectory = $E1: (destroy, backup, rename, NO write, read) 


Errors 


$27: 
$2B: 
$40: 
$44: 
$45: 
$46: 
$47: 
$48: 


$49: 
$4B: 
$52: 
$53: 
$58: 
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IOERR 
NOWRITE 
BADPATH 
PNFERR 
VNFERR 
FNFERR 
DUPERR 
OVRERR 


DIRFULL 
TYPERR 
NOTSOS 
BADLSTCNT 
NOTBLKDEV 


|/O error 

Volume is write-protected 

Invalid pathname syntax 

Path not found 

Volume not found 

Subdirectory file not found 

Attempt to CREATE an existing file 
Overrun error. Either EOF too large or not 
enough disk space 

Directory is full 

Storage _type parameter neither $01 nor $@D 
Not a SOS volume 

Invalid length parameter 

Not a block device 
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9.1.2 DESTROY File Call $C1 
This call deletes the file specified by DESTROY $C1 

the pathname parameter by 

removing the file’s directory entry. Q 

DESTROY releases all blocks used 

by that file back to free space on | pathname 

that volume. pointer 


The file can be either a standard or 
subdirectory file. Volume 
directories cannot be destroyed except by physical reformatting of the 
medium. Character files are destroyed” by the System Configuration 
Program. 


Required Parameters 


pathname: pointer 


This parameter is a pointer to a string containing the pathname of the file 
to be destroyed: the first byte of the string contains the number of bytes in 
the pathname; the remaining bytes contain the pathname itself. 


Comments 


A file cannot be destroyed if it is currently open. If the pathname refers to 
a subdirectory file, then that subdirectory must be completely empty in 
order for the subdirectory to be destroyed. 


Errors 


$27: 
$2B: 
$40: 
$44: 
$45: 
$46: 
$4A: 
$4B: 
$4E: 


$50: 
$52: 
$58: 


lIOERR 
NOWRITE 
BADPATH 
PNFERR 
VNFERR 
FNFERR 
CPTERR 
TYPERR 
ACCSERR 


FILBUSY 
NOTSOS 
NOTBLKDEV 
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|/O error 

Volume is write-protected 
Invalid pathname syntax 

Path not found 

Volume not found 

File not found 

Incompatible file format 
Unsupported file storage type 
File’s access attribute prevents 
DESTROY 

File is open. Request denied. 
Not a SOS volume 

Not a block device 
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9.1.3 RENAME File Call $C2 
This call changes the name of the RENAME $C2 
file specified by the pathname 
parameter to that specified by 0 
new_pathname. Only block files 
may be renamed; character files are ' pathname 
“renamed” by the System pointer 
Configuration Program. 2 

3 
Required Parameters new _patmarie 

pointer 
4 


pathname: pointer 


This parameter is a pointer to a 

string containing the old pathname of the file to be renamed: the first byte 
of the string contains the number of bytes in the pathname; the remaining 
bytes contain the pathname itself. The pathname must refer to either a 
volume directory, subdirectory, or standard file. 


new_pathname: pointer 


This parameter is a pointer to a string containing the new pathname of the 
file to be renamed: the first byte of the string contains the number of bytes 
in the pathname; the remaining bytes contain the pathname itself. The 
pathname can be either a complete or partial pathname. Only the last 

file name of the new pathname may differ from that in the old pathname. 


Comments 


The file must reside on a block device. Both pathname and 
new_pathname must be identical except for the last file name. For 
example, the path /VOL.1/FILE.1 can be renamed /VOL.1/FILE.2 , but 
not /VOL.2/FILE.X or /VOL.1/SUBDIR.A/FILE.X . 


A file may not be renamed while it is open for writing. 


lf new_pathname matches the pathname of an existing file, you will get 
a DUPERR. 


Errors 


$27: 
$2B: 
$40: 
$44: 
$45: 
$46: 
$47: 
$4A: 
$4B: 
$4E: 
$50: 
$52: 
$57: 
$58: 
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lIOERR 
NOWRITE 
BADPATH 
PNFERR 
VNFERR 
FNFERR 
DUPERR 
CPTERR 
TYPERR 
ACCSERR 
FILBUSY 
NOTSOS 
DUPVOL 
NOTBLKDEV 


|/O error 

Volume is write-protected 
Invalid pathname syntax 

Path not found 

Volume not found 

File not found 

Duplicate file name 
Incompatible file format 

File storage type not supported 
File’s access attribute prevents RENAME 
File is open. Request denied. 
Not a SOS volume 

Duplicate volume 

Not a block device 


9.1.4 SET__FILE_INFO 


This call modifies file information 
in the directory entry of the block 
file specified by the pathname 
parameter. If the file is closed, a 
SET FILE INFO call will modify 
the file information immediately. 
This information will be returned 
by any subsequent 

GET FILE INFO calls. If the file 
is open, no file information will be 
modified until the file is closed. 


Required Parameters 


pathname: pointer 


This parameter is a pointer toa 
string containing the file name of 
the file whose directory entry will 
be modified: the first byte of the 
string contains the number of bytes 
in the pathname; the remaining 
bytes contain the pathname itself. 


option list: pointer 


This is a pointer to the optional 
parameter list if length is between 
$01 and $0F; otherwise it is ignored. 


length: 1 byte value 
Range: $00..$0F 


File Calls and Errors 


mo QO DW 


File Call $C3 


SET FILE _INFO$C3 


pathname 
pointer 


option list 
pointer 


access 
value 
file_type 
value 


aux type 
value 


unused 
(7 bytes) 


last_mod 
value 


This is the length of the optional parameter list. It specifies which optional 
parameters are supplied. If length equals $00, no optional parameters are 
supplied: the call does nothing more than error checking. 
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The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take half a 
parameter, but reduces the length to the next defined value. 


®@ = nooptional parameters 

1 = access 

2 = access through file_type 

4 = access through aux_type 

F = access through last_mod 
Optional Parameters 


access: 1 byte value 
Range: $00..$E3 
Default: None 


This parameter specifies the access allowed to the file. Bits 4 through 2 
are reserved for future implementation and must be set to @, otherwise an 
ACCSERR will occur. 


Write-enable 


| - Read-enable 
|D|RN/ B | RESERVED | W | R | 


a Backup 
Rename-enable 
Destroy-enable 
For bits 7, 6, 1, and @, 


% = not allowed 
1 = allowed 


These bits may be altered as the user wishes by the SET __FILE__INFO 
Call. 
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For bit 5, 


® = backup not needed 
1 = backup needed 


This bit is always set when aSET__FILE__INFO call is made. Only 
the Backup III program can clear it. 


file type: 1 byte value 
Range: $00..$FF 
Default: Current value 


This the type identifier for this file. The file_type does not affect the way in 
which SOS deals with the file: it is used only by interpreters to determine 
the internal arrangement and meaning of the bytes in the file. These values 
of file_type are now defined: 


$00 = Typeless file (BASIC or Pascal unknown’ file) 
$01 = File containing all bad blocks on the volume 
$02 = Pascal or assembly-language code file 

$03 = Pascal text file 

$04 = BASIC text file; Pascal ASCII file 

$05 = Pascal data file 

$06 = General binary file 

$07 = Font file 

$08 = Screen image file 

$09 = Business BASIC program file 

$OA = Business BASIC data file 

$0B = Word Processor file 

$2C = SOSsystem file (DRIVER, INTERP, KERNEL) 
$@D, $0E= SOS reserved 

$OF = Directory file (see storage_type) 


$10..sDF= SOS reserved 
$EQ0..$FF= ProDOS reserved 
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aux_type: 2 byte value 
Range: $0000..$FFFF bd 
Default: Current value 


This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field ez 
to store the record size of its data files. If the file is a volume directory 
(storage_type is $0F), these bytes contain the total number of blocks on | 
the volume. 
unused: 7 bytes ~ 
These bytes are here to maintain symmetry with GET__FILE__INFO, and ~— 
are always ignored by SET__FILE_INFO. LL 
last_mod: 4 byte value LJ 
Range: $00000000..SFFFFFFFF 
Default: Current value | 
This is the date and time the file was last closed after being written to. It = 
can be set to a user-defined value, or you can use the GET__ TIME call 
(see the Utility calls) and form this value from the current time. The LJ 
last_ mod parameter is organized as two 2-byte words, each stored low 
byte first: = 


byte 1 byte @ 
7654321¢46,765 432146 


— 
ese 
— 
CON cAOONo ae 
— 
haa 


byte 3 byte 2 


The ranges for these fields are as follows: 


Year: 0.99 ($00..$63) ~ 
Month: 0.12 ($00..$0C) | 
Day: 9.31 ($00..$1F) ~ 
Hour: 0.24 ($00..$18) LJ 
Minute: 0.60 ($00..$3C) 
A zero value for the month or day means that no value was set. _ 
= 


J 


io 


J 
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No checking is performed on this parameter. If you use the GET __ TIME 
call, you must pack the 18-byte time parameter from that call into the 
proper format for the SET__FILE__INFO call’s last_mod parameter. 


Comments 


The default value for all optional parameters that are omitted is the current 
value of that attribute of the file: for example, omitting the last_mod 
parameter results in no change to that file’s modification date and time. 


The same required and optional parameter lists can be used for 
GET FILE INFO. In fact, you can perform a 


GET FILE_INFO, examine and perhaps alter the values in the 
parameter lists, and then perform aSET FILE INFO to update 
the file's attributes. 


You can perform SET__FILE__INFO on any block file, regardless of the 
current value of its access attribute. In this call, therefore, an access error 
can result only from passing an invalid access parameter. 


SET FILE_INFO affects a file’s directory entry only. It does not affect 
the FCB entry for any access path to the file. Specifically, if you open a file 
with read/write access, then useaSET_ FILE INFO call to change the 
access to read-only, you still write to the file via that access path, but you 
cannot open another access path. This is because the access field in the 
file’s directory entry will not be updated until the file is closed, and the 
FCB entries will not be updated at all: so, as far as SOS is concerned, this 
is still a read/write file, for which only one access path is allowed. As soon 
as you Close the file, however, the new access value will be stored in the 
directory entry, and multiple read-only access paths can be opened. 


Errors 


$27: 
$2B: 
$40: 
$44: 
$45: 
$46: 
$4A: 
S4B: 
$4E: 
$52: 
$53: 
$58: 
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IOERR 
NOWRITE 
BADPATH 
PNFERR 
VNFERR 
FNFERR 
CPTERR 
TYPERR 
ACCSERR 
NOTSOS 
BADLSTCNT 
NOTBLKDEV 


\/O error 

Volume is write-protected 
Invalid pathname syntax 
Path not found 

Volume not found 

File not found 

Incompatible file format 
Unsupported file storage type 
Access parameter invalid 
Not a SOS volume 

Length parameter invalid 
File is not on a block device 


9.1.5 GET_FILE_INFO 


This call returns file information 
from the directory entry of the 
block file specified by the 
pathname parameter. 


Required Parameters 


pathname: pointer 


This parameter is a pointer toa 
string containing the pathname of 
the file whose directory entry 
information will be returned: the 
first byte of the string contains the 
number of bytes in the pathname; 
the remaining bytes contain the 
pathname itself. 


option list: pointer 


This is a pointer to the optional 
parameter list if length is between 
$01 and $@F; otherwise it is ignored. 


length: 1 byte value 
Range: $00..$0F 


This is the length of the optional 
parameter list. If length equals $00, 
no optional parameters are 
returned: the call does nothing 
more than error checking. 


The values below tell the number 
of bytes in a list with complete 
parameters. If SOS receives an 
intermediate value, it does not take 
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File Call $C4 


GET _FILE_INFO$C4 


) 
L pathname 
pointer 
2 
option list 
pointer 
4 
S. 
0 access 
result 
1 file_type 
result 
2 
aux type 
P result 
4 storage_type 


result 


blocks used 
result 


last_mod 
result 


E 


half a parameter, but reduces the length to the next defined value. 
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$00 = nooptional parameters 

$01 = access 

$92 = access through file type 
$04 = access through aux_type 
$05 = access through storage type 
$09 = access through EOF 

$9B = access through blocks used 
$9F = access through last_mod 


Optional Parameters 
access: 1 byte result 
Range: $00..$C3 
This parameter returns the access allowed to the file. Bits 4 through 2 are 
reserved for future implementation and are now set to @. 


Write-enable 


Read-enable 
| - 


ro [AN[s | Resenveo [Ww] FR) 
| Ee Backup 
Rename-enable 
Destroy-enable 


For bits 7, 6, 1, and @, 
% = not allowed 
1 = allowed 

For bit 5, 
% = backup not needed 
1 = backup needed 

file type: 1 byte result 
Range: $00..$FF 


This the type identifier for this file. The file_type does not affect the way in 
which SOS deals with the file: it is used only by interpreters to determine 


Be & 


Rene & 


c- 


Ez’ 


EEREEE EH & 
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the internal arrangement and meaning of the bytes in the file. These 
values of file_type are now defined: 


$00 = Typeless file (BASIC or Pascal “unknown’ file) 
$01 = File containing all bad blocks on the volume 
$62 = Pascal or assembly-language code file 

$03 = Pascal text file 

$04 = BASIC text file; Pascal ASCII file 

$05 = Pascal data file 

$06 = General binary file 


$07 = Font file 


$08 = Screen image file 

$09 = Business BASIC program file 

$0B = Word Processor file 

$OC = SOS system file (DRIVER, INTERP, KERNEL) 
$0D, $0E = SOS reserved 

$OF = Directory file (see storage_type) 


$10..$DF = SOS reserved 
$EQ..$FF = ProDOS reserved 


aux_type: 2 byte result 
Range: $0000..$FFFF 


This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field 
to store the record size of its data files. If the file is a volume directory 
(storage_type is $F), these bytes contain the total number of blocks 
on the volume. 


storage type: 1 byte result 
Range: $01..$03, $0D, $0F 


This byte describes the external format of the file: how the blocks that 
compose the file are stored on the volume. 


$01 = seedling file ( @ <= EOF <= 512 bytes) 
$02 = sapling file ( 512 < EOF <= 128Kbytes) 
$03 = tree file (128K < EOF <_ 16M bytes) 
$@D = subdirectory file 


$@F = volume directory file 
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These structures are fully explained in Chapter 5. In brief, seedling files 
are stored as one data block; sapling files are stored as one index block 
and up to 256 data blocks; tree files are stored as one root index block, 
up to 127 subindex blocks, and up to 32,767 data blocks. Directories and 
subdirectories do not use index blocks, and instead are stored as doubly- 
linked lists of blocks. 


EOF: 4 byte result 
Range: $00000000..$00FFFFFF 


This is the position of the end of file marker. It indicates the number 

of bytes readable from the file. This is the EOF value stored in the file’s 
directory entry when the file was created or last closed. It is accurate 
only if the file is not open for writing. If the file is open for writing, the 
current EOF (stored in the file’s FCB entry) can be read by the 

GET EOF call. 


blocks _used: 2 byte result 
Range: $0000..$FFFF 


lf the file is a standard file or subdirectory (storage_type is $01, $02, $03, 
or $0D), blocks_used is the total number of blocks (including index 
blocks) currently used by the file. 


If the file is a sparse file, the blocks_used value can be 
substantially less than one would expect from the EOF. 


If the file is a volume directory (storage_type is $0F), blocks used is the 
total number of blocks used by all files on the volume. 


last_mod: 4 byte result 
Range: $00000000..$FFFFFFFF 


This is the date and time the file was last closed after being written to. If 
the file has never been written to, these bytes are the same as the creation 
date of the file. SET FILE INFOcan also change the modification date. 


byte 1 byte @ 
765 4329%@;7 6543 214 


byte 3 byte 2 
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The ranges for these fields are as follows: 


Year: 0.99 ($00..$63) 
Month: @..12 ($0@..$0C) 
Day: 0.31 ($00..$1F) 
Hour: Q..24 ($00..$18) 
Minute:  @..60 ($00..$3C) 


A zero value for the month or day means that no value was set. 


Comments 


This call can be performed when the file is either open or closed. 

The same required and optional parameter lists can be used for 

SET FILE INFO.AGET_ FILE INFO call to an open file will return 
file information from the directory entry, not access path information from 
the FCB entry. This is not surprising, since the GET FILE INFO call 
refers to a file by its pathname, not its ref_num. For example, if you have 
changed the EOF since the file was opened, GET_ FILE INFO will not 
return the current value. 


Errors 

$27: lIOERR |/O error 

$40: BADPATH Invalid pathname syntax 

$44: PNFERR Path not found 

$45: VNFERR Volume not found 

$46: FNFERR File not found 

$4A: CPTERR Incompatible file format 

$4B: TYPERR Unsupported file storage type 
$52: NOTSOS Not a SOS volume 


$53: BADLSTCNT Length parameter invalid 
$58: NOTBLKDEV Nota block device 


eS ft. vw 
SEER HRERHR RRR RRRReReReReee ea 
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9.1.6 VOLUME File Call $C5 
When given the name of a device, VOLUME $C5 
this call returns the volume name of 
the volume contained in that Q 
device, the number of blocks on 
that volume, and the number of 1 dev cians 
currently unallocated blocks on pointer 
that volume. 2 

3 
Required Parameters vol_name 

pointer 

dev_name: pointer : 
This parameter is a pointer toa : total_blocks 
string containing the device name: result 
the first byte of the string contains : 
the number of bytes in the device . 
name; the remaining bytes contain free_blocks 
the device name itself. result 


vol_name: pointer 


This is a pointer to a buffer at least $10 bytes long into which the volume 
name will be returned: the first byte in the buffer contains the number of 
bytes in the volume name; the rest contain the name itself. 


total_blocks: 2 byte result 
Range: $0000..$FFFF 


This is the total number of blocks contained by the volume in the 
specified block device. 


free_blocks: 2 byte result 
Range: $0000..$FFFF 


This is the number of unallocated blocks contained by the volume in the 
specified block device. 


Comments 


The dev_name must point to the name of a block device. 


Errors 


$10: 
$27: 
$45: 
S4A: 
$52: 
$58: 
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DNFERR 
lIOERR 
VNFERR 
CPTERR 
NOTSOS 
NOTBLKDEV 


Device not found 

I/O error 

Volume not found 
Incompatible file format 
Not a SOS volume 

Not a block device 
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_ 9.1.7 SET__PREFIX File Call $C6 
- This call sets the current SOS SET__ PREFIX $C6 
prefix pathname to that specified by 
— pathname. 0 
1 
a | Required Parameters pathname 
9 pointer 
a | pathname: pointer 
oe This parameter is a pointer to a string containing the pathname that will 
replace the current prefix pathname: the first byte of the string contains 
—_ the number of bytes in the pathname; the remaining bytes contain the 
pathname itself. This pathname specifies a volume directory or 
an subdirectory, not a character file or a standard file. 
= Comments 
The system prefix is appended to the beginning of any pathname not 
beginning in a volume name or device name: a volume name is preceded 
ry by aslash, and a device name begins with a period. 
ry If the new prefix begins with a volume name, only syntax checking is 
performed on it: SOS does not verify that the directory file specified by 
the prefix is actually on line. If the new prefix begins with a device name, 


SOS substitutes the corresponding volume name: the SOS prefix always 
a | begins with a volume name. 


me | The prefix can be reset to null by passing a pathname with a length of 
zero characters. 


Upon system boot, the prefix is initialized to the volume directory name of 
ae | the boot disk. 


rs The pathname can optionally terminate with a “7”. 


Errors 


$27: 
$40: 
$58: 
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lIOERR 
BADPATH 
NOTBLKDEV 


|/O error 
Invalid pathname syntax 
Not a block device 
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9.1.8 GET__PREFIX File Call $C7 


This call returns the current SOS GET_ PREFIX $C7 
prefix pathname. 


Required Parameters 
pathname 


pointer 


pathname: pointer 


This parameter is a pointer to a 

string into which SOS is to store 3 
the current prefix pathname: the 

first byte of the string contains 

the number of bytes in the prefix; the remaining bytes contain the 
prefix itself. 


length: 1 byte value 
Range: $00..$FF 
Default: $80 


This is the maximum number of bytes in the pathname buffer. This should 
be set as long as the longest prefix the interpreter accepts: SOS will 
accept up to 128 ($80) bytes. A BTSERR is returned if the pathname is 
longer than length. 


Comments 


If the SOS prefix pathname has been set to the null string (no prefix), the 
null string is returned. 


lf the prefix pathname is not null, it is terminated with a slash. 


If the first name in the prefix pathname is a volume name, the pathname 
begins with a slash. 


Errors 


$4F: BTSERR Buffer too small 
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9.1.9 OPEN 


This call causes SOS to open an 
access path (allowing read-access, 
write-access, or both) to the file 
specified by pathname. For this 
access path, SOS makes an entry in 
the file control block and allocates a 
1924-byte I/O buffer. This buffer 
holds the contents of one index 
block (if the file has any) and one 
data block. 


Required Parameters 


pathname: pointer 


This is a pointer to a string in 
memory containing the pathname 
of the file to be opened: the first 
byte is the number of characters in 
the pathname; the remaining bytes 
are the characters of the pathname 
itself. It may be any block or 
character file. 


ref_num: 1 byte result 
Range: $01..$10, $81..$90 
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File Call $C8 


OPEN $C8 


pathname 
pointer 


3 ref_num 
result 


option list 
pointer 


pages 
value 


req access 
value 


io_buffer 
pointer 


The reference number is assigned when an access path to a file is 
opened. It uniquely identifies an access path to the file: any open-file call 
will operate on a single access path, not the file itself. 


option list: pointer 


This points to optional parameter list if length is between $01 and $04; 


otherwise it is ignored. 
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length: 1 byte value 
Range: $00..$04 


This is the length in bytes of the optional parameter list. It specifies which 
optional parameters are supplied. 


The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take halfa 
parameter, but reduces the length to the next defined value. 


$29 = nooptional parameters 
$01 = req access 
$04 = req_access through io buffer 


Optional Parameters 


req_access: 1 byte value 
Range: $00..$03 
Default: $00 


This is the requested file access. SOS compares this parameter with the 
file’s current access-attribute byte to ensure that the intended file 
operations are permitted. A $@@ requests as much access as permitted. 


$00 = Openas permitted 


$01 = Open for reading only 
$@2 = Open for writing only 
$03 = Open for reading and writing 


A standard file that is already open for writing may have only one access 
path: a req_access of $09 will open the existing access path for reading as 
well. A standard file on a write-protected volume may never be opened 
for writing; a req_access of $00 will open such a file for reading only. 


A character file may have multiple access paths with read-access, write- 
access, or both, if the file’s device allows such access. 
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pages: 1 byte value 
Range: $00 or $04 
Default: $00 


This is the length in 256-byte pages of a caller-supplied I/O buffer. If equal 
to $0, then SOS finds its own buffer, ignoring the io_buffer parameter 
below. If equal to $04, then SOS will use the 1824-byte buffer pointed to by 
io_buffer. Any value except $00 or $04 is invalid. 


If pages is nonzero, you must specify an io_buffer parameter. 


In general, it is preferable to let SOS allocate an I/O buffer. 


io_buffer: pointer 


This is an indirect pointer to a caller-supplied I/O buffer if and only if the 
pages parameter is nonzero. 


Comments 
On block files, multiple access paths for read-access are permitted. 


On block files, only one access path for writing is permitted: no 
other access path, even for reading only, is permitted at the same time. 


Multiple access paths on character files for both read- and write-access 
are permitted. 


OPEN sets the file level of the opened file to the current system file level 
(see SET LEVEL and GET_ LEVEL). Unless the file level is raised, a 
subsequent CLOSE or FLUSH of multiple files will close or flush this file. 


The option list and length parameters are ignored when OPENing 
character files; no optional parameters are used. 
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Errors 

$27: lIOERR I/O error 

$40: BADPATH Invalid pathname syntax han 

$41: CFCBFULL Character File Control Block table full 

$42: FCBFULL Block File Control Block table full = 

$44: PNFERR Path not found 

$45: VNFERR Volume not found | 

$46: FNFERR File not found 

$4A: CPTERR Incompatible file format = 

$4B: | TYPERR Unsupported file storage type 

$4E: ACCSERR File doesn’t allow this req_access = 

$4F: BTSERR User-supplied buffer too small 

$50: FILBUSY Can't open for multiple writes | 

$52: NOTSOS Not a SOS diskette 

$53: BADLSTCNT Length parameter invalid = 

$54: OUTOFMEM Out of free memory for buffer 

$55: BUFTBLFULL Buffer table full Lud 

$56: BADSYSBUF Invalid system buffer parameter 

$57: DUPVOL Duplicate volume | 
= 
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9.1.10 NEWLINE File Call $C9 
This call allows the caller to turn NEWLINE $C9 
newline read mode on or off. Once 
newline mode has been turned on, i) 
any subsequent READ operation 
will immediately terminate if the 1 
newline character is encountered in 
the input byte stream. e | isnewine 
: 
Required Parameters value 


ref_num: 1 byte value 
Range: $01..$10, $81..$90 


This is the reference number of the access path, provided by the 
OPEN call. 


is_newline: 1 byte value 
Range: $00..$FF 


The high bit of this byte determines whether newline read mode is on or 
off. If it is set (is_ newline > $7F), newline mode is on; otherwise, newline 
mode is off. 


newline_char: 1 byte value 
Range: $00..$FF 


This byte indicates the character used to terminate read requests. If 
newline read mode is off, this parameter is ignored. 
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Comments 
The newline_char byte need not have any ASCII interpretation. 


A NEWLINE call to a character file implicitly does aD —_CONTROL call 


number 2 (set newline mode) to the device driver represented by that file. 


This changes the newline mode of all access paths to that character file. 


Errors 


$43: BADREFNUM Bad reference number 
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_ 9.1.11 READ File Call $CA 
_ This call attempts to transfer READ $CA 
request _ count bytes, starting from 
= the current file position (mark), 0 
from the I/O buffer of the file access 
= path specified by ref_num into the 1 
interpreter’s data buffer pointed to 
- by data_buffer. If newline read 
) mode is enabled and the newline ee ca 
i character is encountered before 
| request_count bytes have been 
read, then the transfer count 4 
me | ‘ = request count 
parameter will be less than value 
_ request _count and exactly equal to S 
the number of bytes transferred, 
= including the newline byte. OT deers comin 
3 result 
7 
— Required Parameters 
| ref_num: 1 byte value 
Range: $01..$10, $81..$90 
Py This is the reference number of the access path to be read from, obtained 
_ through an OPEN call. 
__ data_buffer: pointer 
This is a pointer to the first byte of a caller-supplied buffer at least 
a | request_count bytes long. 
ae | request_count: 2 byte value 
Range: $0000..$FFFF 
yy This is the number of bytes SOS is to read from the file into the buffer. If 
_ request_count equals $0000, the READ call does error checking only: no 
bytes are read. 
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transfer_count: 2 byte result 
Range: $0000..request_count 


If a READ is successful, the number of bytes transferred to the data buffer 
is returned in this parameter. If a READ is completely unsuccessful, 
transfer_count equals $0009. 


Comments 


READ advances the current file position (mark) by one byte for each byte 
transferred. It will advance the mark up to the end-of-file (EOF) marker, 
which points one byte past the last byte in the file. READ fails with an 
EOFERR if and only if the mark already equals EOF; in this case, no bytes 
are transferred and transfer_count returns zero. 


lf a READ operation spans several contiguous blocks on a disk, SOS 
transfers whole blocks directly to the interpreter’s data buffer, bypassing 
the I/O buffer; partial blocks go through the I/O buffer. This optimization 
improves performance, but is otherwise invisible to the interpreter writer 
and user. 


Errors 

$27: IOERR |/O error 

$43: BADREFNUN _ Invalid reference number 

$4C: EOFERR End of file has been encountered 


$4E: ACCSERR File not open for READing 
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9.1.12 WRITE File Call $CB 
This call attempts to transfer WRITE $CB 
request_count bytes, starting from 
the current file position (mark), Q 
from the buffer pointed to by 
data_buffer to the open file } 
specified by ref_num. 
data_buffer 

Required Parameters 3 pes 
ref_num: 1 byte value 4 moueaceusl 

s u 

Range: $01..$10, $81..$90 ae 

This is the reference number of the 5 
file to be written to, obtained by an 
OPEN call. 


data_buffer: pointer 


This is a pointer to a caller-supplies buffer from which SOS is to draw the 
bytes to be written to the file. This pointer is not modified by SOS. 


request_count: 2 byte value 
Range: $0000..$FFFF 


This is the number of bytes to be written to the file. 


Comments 


lf WRITE ends with an OVRERB,, it has written all the bytes that it can to 
the file: it will not tell you how many it has written. Otherwise, WRITE 
always succeeds or fails completely. 


Bytes written to a file may be stored in an I/O buffer, and sent a 
buffer-load at a time. For block files, WRITE physically alters the bytes on 
the volume only when a block of bytes has been written to the file: this 
occurs automatically when the mark crosses a block boundary. To ensure 
that information in the buffer has been updated on the volume, use the 
FLUSH call. 
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Errors 


$27: 
$2B: 
$43: 
$48: 
$4E: 


lIOERR 
NOWRITE 
BADREFNUM 
OVRERR 
ACCSERR 


I/O error 

Volume write-protected 

Invalid reference number 

Not enough room in file or on volume 
Tried to write to read-only file 
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_  —- 9.1.13 CLOSE File Call $CC 
_ The file access path specified by CLOSE $CC 
ref_num is closed. Its file control 
oat block (FCB) entry is deleted, and if Q $01 
| the file is a block file that has been aaa, 
_ written to, its |/O buffer is written 1 
| to the file. The directory entry of a 
_ block file is then updated from the 
} FCB entry. Further file operations using that ref_num will fail. 
= 
Required Parameters 
a | 
ref_num: 1 byte value 
— Range: $00..$10, $81..$90 
— This is the reference number of the file to be closed, obtained by an 
OPEN call. 
Comments 
—_ 
If a block file has been written to, a CLOSE call changes the modification 
Py date and time of the file to the current date and time. 
- If ref_num equals $09, all open files are closed whose file level (see 
SET LEVEL, GET_ LEVEL) is greater than or equal to the current 
Py system level. 
- If an error occurs while closing multiple files, all files that can be closed 
_ will be, and CLOSE will return the error number of the last error that 
| occurred. CLOSE will not tell you which files were closed and which 
_ were not. 
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Errors 


$27: IOERR I/O error 

$2B: NOWRITE Volume is write-protected 
$43: BADREFNUN Invalid reference number 
$48: OVRERR Not enough room on volume 
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9.1.14 FLUSH File Call $CD 


If a previous WRITE call has left FLUSH $CD 
any data in a block file’s |/O buffer, 
the FLUSH call writes these data to 
the volume the file is stored on and 
clears the buffer. If the I/O buffer is 
empty, FLUSH simply returns an 
error code of $00. 


Required Parameters 


ref_num: 1 byte value 
Range: $00..$10 


This is the reference number of the block file access path to be FLUSHed, 
obained from an OPEN call. Since the file is open for writing, this access 
path is the only one. 


Comments 


FLUSH must be used only on block file access paths that are open 
for writing. 


If the ref_num equals $9, all open files are FLUSHed whose file level (see 
SET LEVEL, GET_ LEVEL) is greater than or equal to the current 
system file level. 


FLUSH is a time-consuming call: if it is used when not needed, 
performance will suffer. 
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Errors 

$27: IOERR 

$2B: NOWRITE 
$43: BADREFNUM 
$48: OVRERR 

$58: NOTBLKDEV 


[/O error 

Volume is write-protected 
Invalid reference number 
Not enough room on volume 
Not a block device 


7 


[ | 


r 


if 


E 


9.1.15 SET_MARK 


This call changes the current file 
position (mark) of the file access 
path specified by ref_num. The 
mark can be changed to an 
absolute byte position in the file, or 
to a position relative to the EOF or 
the current mark. 


Required Parameters 


ref_num: 1 byte value 
Range: $01..$10 


This is the reference number of the 
block file access path whose mark 
is to be moved, obtained through 
an OPEN call. 


base: 1 byte value 
Range: $00..$03 
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File Call $CE 


SET_MARK $CE 


) $03 
, ref_num 
value 
base 
: 


displacement 
value 


This is the starting byte position in the file from which to calculate the 


new mark position. 


$00 = Absolute, byte $00000000..$00FFFFFF 


$01 = Backward from EOF 
$02 = Forward from current mark 
$03 = Backward from current mark 


displacement: 4 byte value 


Range: $00000000..$00FFFFFF 


This is the number of bytes the mark is to move from the starting location 
specified by the base parameter. The final computed position must lie 
between $@ and the current EOF ($0 <= mark <= EOF <= $FFFFFF). 
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= | 
Errors | 
= 
$27: IOERR |/O error | 
$43: BADREFNUM Invalid reference number = 
$4D: POSNERR Position out of range | 
$58: NOTBLKDEV Nota block device LJ 
— | 
= 
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me) 
a 91.16 GET_MARK File Call $CF 
_ This call returns the current file GET_ MARK $CF 
} position (niark) of the block file 
= access path specified by ref_num. 0 $02 
1 ref_num 
_ Required Parameters value 
2 
— ref_num1: 1 byte value 
Range: $01..$10 3 care 
— result 
This is the reference number of the 4 
—_ file whose current position is to be 
returned. 5 


mark: 4 byte result 
— Range: $00090000 through 
current EOF value 


This is the current mark position in the file. 


Errors 


$43: BADREFNUN _e Invalid reference number 
$58: NOTBLKDEV Nota block device 
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9.1.17 SET_EOF 


This call changes the end-of-file 
marker (EOF) of the block file 
whose access path is specified by 
ref_num. The EOF can be changed 
to an absolute byte position, or toa 
position relative to the current EOF 
or the current mark. 


If the new EOF is less than the 
current EOF, empty blocks at the 
end of the file are released to the 
system and their data are lost. If 
the new EOF is greater than the 
current EOF, blocks are not 
physically allocated for unwritten 
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File Call $D@ 


SET EOF $D0 


displacement 
value 


data. (This is one way of creating a sparse file.) If a program attempts to 
read from these newly created logical positions before they have been 
physically written to, SOS supplies a null ($00) for each byte requested. 


Required Parameters 


ref_num: 1 byte value 
Range: $01..$10 


This is the reference number of the file whose EOF is to be changed, 
returned by an OPEN call. It must refer to a block file open for writing, and 


is thus the file’s sole ref_num. 
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base: 1 byte value 
Range: $00..$03 


This is the position in the file from which to calculate the new value of 
EOF, (the current number of bytes in the file). 


$00 = Absolute, byte $000000..$FFFFFF 

$01 = Backward from current EOF 

$02 = Forward from current mark position 
$03 = Backward from current mark position 


displacement: 4 byte value 
Range: $09900000..$00FFFFFF 


This is the number of bytes the EOF is to move from the starting position 
specified in the base parameter. The final computed position must be 
greater than or equal to $000000, and less than or equal to $FFFFFF. 


Comments 


The file must be a block file currently open for writing. Since such a file 
can have only one access path, the ref_num specifies the file, as well as 
the access path. 


This call updates the EOF field in the file control block entry, but not the 
EOF field in the file’s directory entry: the latter is updated only when the 
access path is closed. For this reason,a GET__FILE__INFO call toan 
open file will not always return the current EOF. A GET EOF call will. 


Errors 


$27: IOERR I/O error 

$2B: NOWRITE Volume write-protected 

$43: BADREFNUM Invalid reference number 

$4D: POSNERR Position out of range 

$4E: ACCSERR Tried to move EOF of read-only file 
$58: NOTBLKDEV Nota block device 
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9.1.18 GET_EOF File Call $D1 


This returns the current end-of-file GET_EOF $D1 
(EOF) position of the file specified 
by ref_num. 


Required Parameters 


ref_num: 1 byte value 
Range: $01..$10 EOF 

result 

This is the reference number of the 
file whose current position is to be 

returned, provided by an OPEN call. 


EOF: 4 byte result 
Range: $00000000..$00FFFFFF 


This is the number of bytes that can be read from the file. 


Errors 


$43: BADREFNUM _Invalid reference number 
$58: NOTBLKDEV Nota block device 
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9.1.19 SET_LEVEL File Call $D2 
This call changes the current value SET LEVEL $b2 

of the system file level. All on 

subsequent OPENSs will assign this 0 

level to the files opened. All 


subsequent CLOSE and FLUSH 1 
operations on multiple files (using 

a ref_num of $09) will operate on 

only those files that were opened with a level greater than or equal to the 
new level. 


Required Parameters 


level: 1 byte value 
Range: $01..$03 


This specifies the new file level. 


Comments 


The system file level is set to $01 at boot time. 


Errors 


$59: LEVLERR Invalid file level 
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31.20 GET. LEVEL File Call $D3 
This call returns the current value GET_ LEVEL $D3 

of the system file level. See 

SET_ LEVEL, OPEN, CLOSE, and ‘ 

FLUSH. 


Required Parameters 


level: 1 byte result 
Range: $01..$03 


This parameter returns the current file level. 


Comments 


The file level is set to $01 at boot time. 


9.2 File Call Errors 


These error messages can be generated by SOS file calls; in addition, 
some of these calls may generate device call errors, described in section 
10.2. Other errors are listed in Appendix D. 

$49: Invalid pathname syntax (BADPATH) 


The pathname violates the syntax rules in Chapter 4 of Volume 1. 


$41: Character File Control Block full (CFCBFULL) 


The Character File Control Block (CFCB) table can contain a maximum 
of $18 entries. Opening the same character file more than once will return 
the same ref_num (that is, will not consume an additional entry). 


SOS Reference Manual 


Ll 
$42: Block File or Volume Control Block full (FCBFULL) 
The Block File Control Block (BFCB) table can contain a maximum of — 
$19 entries. The Volume Control Block (VCB) table can contain a 
maximum of $08 entries. Opening the same block file more than than — 
once returns a different ref_num and consumes a new entry in the BFCB 
table. Every volume with an open file on it, whether it is mounted ona — 
device or not, consumes one entry in the VCB table. 
$43: Invalid reference number (BADREFNUM) 
The ref_num input parameter does not match the ref_num of any currently 
open file. This error is also returned if the currently open file is marked | 
with a bad storage _type; only $01 through $04, $@D, and $0F are allowed. _ 


$44: Path not found (PNFERR) 


Some file name in the pathname refers to a nonexistent file. The — 
pathname’s syntax is legal. 


$45: Volume not found (VNFERR) 

The volume name in the pathname refers to a nonexistent volume _ 
directory. The pathname’s syntax is legal. LJ 
$46: File not found (FNFERR) F 


The last file name in the pathname refers to a nonexistent file. The 
pathname’s syntax is legal. Note that a missing volume directory file bal 
returns VNFERR instead of FNFERR. 


— 
$47: Duplicate file name (DUPERR) 
An attempt was made to CREATE a file using a pathname that already ™ 
belongs to a file, or a RENAME was attempted using a new_pathname = 
that already belongs to a file. 
$48: Overrun on volume (OVRERR) = 
An attempt to allocate blocks on a volume during a CREATE or WRITE = 
operation failed due to lack of space on the volume. This error also is 
returned on an invalid EOF parameter. hand 
Lj 
LJ 
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$49: Directory full (DIRFULL) 


No more entries are left in the root/subdirectory. Thus no more files can 
be added (CREATEd) in this directory until another file is DESTROYed. 


$4A: Incompatible file format (CPTERR) 


The file is not backward compatible with this version of SOS. 


$4B: Unsupported storage type (TYPERR) 


The CREATE call accepts only two values for the storage_type parameter: 
$01 (standard file) or $9D (subdirectory file). 


$4C: End of file would be exceeded (EOFERR) 
A READ call was attempted when the mark was equal to the EOF. 


$4D: Position out of range (POSNERR) 


A base/displacement parameter pair produced an invalid mark or EOF. 


$4E: Access not allowed (ACCSERR) 

The user attempted to access (RENAME, DESTROY, READ from, or 
WRITE to) a file in a way not allowed by its access attribute. 

$4F: Buffer too small (BTSERR) 


The user supplied a buffer too small for its purpose. 


$50: File busy (FILBUSY) 

An attempt was made to RENAME or DESTROY an open file or to OPEN 
a block file already open for writing. 

$51: Directory error (DIRERR) 

The directory entry count disagrees with the actual number of entries in 
the directory file. 

$52: Not a SOS volume (NOTSOS) 


The volume in the block device contains a directory that is not in SOS 
format: it may be an Apple II Pascal or DOS 3.3 volume. 
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$53: Length parameter invalid (BADLSTCNT) 


The length supplied for the optional parameter list is invalid. 


$54: Out of memory (OUTOFMEM) 

There is not enough free memory for the SOS system buffer. The user 
must release some memory to SOS to allow the system to use it. 

$55: Buffer Table full (BUFTBLFULL) 


The Buffer Table can contain a maximum of $1@ entries. 


$56: Invalid system buffer parameter (BADSYSBUF) 


The buffer pointer parameter must be an extended indirect pointer. 


$57: Duplicate volume (DUPVOL) 


A SOS call asked SOS to bring a volume on-line on a particular block 
device. The request was denied because a volume with the same name on 
another block device is currently on line and contains a currently open 
file. 


$58: Not a block device (NOTBLKDEV) 


Only OPEN, NEWLINE, READ, WRITE, and CLOSE file calls can 
reference a character file. For example, CREATE is not permitted on the 
character file .PRINTER. 


$59: Invalid level (LVLERR) 

The SET__LEVEL call received a parameter less than $01 or greater than 
$03. 

$5A: Invalid bit map address (BITMAPADR) 


An index block contained a block number that, according to the bit map, 
is not physically available on the volume: usually this indicates that the 
blocks on the volume have been scrambled. 
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58 10.1 Device Calls 

59 10.1.1 D_ STATUS 

63 10.1.2 D_ CONTROL 

65 10.1.3 GET DEV NUM 
67 10.1.4 D_ INFO 

71 10.2 Device Call Errors 
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Device Calls 


These SOS calls operate directly on devices. 


$82:D_ STATUS 

$83: D CONTROL 
$84: GET_DEV_ NUM 
$85:D INFO 
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10.1.1 D__STATUS Device Call $82 
This call returns status information D_ STATUS $82 

about a particular device. The 

information can be either general 0 $03 

or device-specific information. 


D__STATUS returns information 1 a 


about the internal status of | Sate” 
the device or its driver; S 
GET DEV_INFOreturns 
information about the external status 3 status list 


of the driver and its interface pointer 
with SOS. 4 


Required Parameters 


dev_num: 1 byte value 
Range: $01..$18 


This is the device number of the device from which to read status 
information, obtained from the GET__ DEV__NUM call. Each device in the 
system has a unique device number assigned to it when the system is 
booted. Device numbers do not change unless the SOS.DRIVER file is 
changed and the system is rebooted. 


status code: 1 byte value 
Range: $00..$FF 


This is the number of the status request being made. All device drivers 
respond to the following requests: 


Block devices only: 
$00 Return driver’s status byte 
Character devices only: 


$00 No effect 
$01 Return driver's control block 


$02 Return newline status 
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Device drivers also may respond to other status codes. The complete list 
of status requests available for a device driver is included in the 
documentation accompanying that driver. 


status list: pointer 


This is a pointer to the buffer in which the device driver returns its status. 
For the three requests above, the buffer is in one of these three formats: 


7 6 5 4 3 2 1 
Ce 


Bit 0 


device 
write-protected 


device 
busy 


Bit Meaning 


BSY If 1, device is busy 
WPR __ If 1, device or medium is write-protected 


Figure 10-1. Block Device Status Request $00 


status 
list 
| (values) | 


Figure 10-2. Character Device Status Request $01 


The status list for each driver has a different format. See the manual 
describing that driver. 
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n 
value 
iia newline_char 
| Figure 10-3. Character Device Status Request $02 
The newline character is called the termination character in the Apple III 
—_ Standard Device Drivers Manual. 
=~ Each driver that defines its own additional status requests also defines 
buffer formats for those requests; see the manual describing that driver. 
_ Comments 
7 The length of the buffer pointed to by status_list must vary depending 
} upon the particular status request being made. 
| Errors 
| $11: BADNUM Invalid device number 
Po $21: CTLCODE _ Invalid status code 
$23: NOTOPEN Character device not open 
rr $25: NORESRC __ Resource not available 
$30..$3F Device-specific error 
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_ 10.1.2 D__CONTROL Device Call $83 
- This call sends control information D_CONTROL $83 
to a particular device. The 
a information can be either general 0 
or device-specific information. 
—_ D CONTROL operates on 1 
character devices only. ; 
Required Parameters 3 
—_ control _list 
pointer 
dev_num: 1 byte value 4 
ry Range: $01..$18 
ae This is the device number of the device to which to send control 
} information, obtained from the GET _DEV_ NUM call. Each device in the 
—_ system has a unique device number assigned to it when the system is 
booted. Device numbers do not change unless the SOS.DRIVER file is 
en changed and the system is rebooted. 
_ control_code: 1 byte value 


Range: $00..$FF 


me | This is the number of the control request being made. All character device 
drivers respond to the following requests: 


$00 Reset device 
ry $01 Restore driver’s control block 
$02 Setnewline mode and 
ry character 
me Block devices do not respond to any control requests. 
= Device drivers also may respond to other control requests. The complete 
list of control requests available for a device driver is included in the 
a | documentation accompanying that driver. 
ae | control _list: pointer 


This is a pointer to the buffer from which the device driver draws the 
control information. For the two requests above, the buffer is in one of 
these two formats: 


SOS Reference Manual 


control 


list _ 
| (values) 1 
Figure 10-4. Character Device Control Code $01 _ 
The status list for each driver has a different format. See the manual — 
describing that driver. 
is_newline = 
newline_char 
. 
Figure 10-5. Character Device Control Code $62 
The newline character is called the termination character in the Apple II! 
Standard Device Drivers Manual. = 
Each driver that defines its own additional control requests also defines hana 
buffer formats for those requests; see the documentation for that driver. 
Comments | 
The length of the buffer pointed to by control_list must vary depending 
upon the particular control request being made. = 
Errors 
$11: BADNUM Invalid device number 
$21: CTLCODE Invalid control code — 
$23: NOTOPEN Character device not open 
$25: NORESRC Resource not available — 
$26: BADOP No control of block devices allowed 
$30..$3F Device-specific error = 
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_ 10.1.3 GET__DEV_.NUM Device Call $84 
This call returns the device number GET _DEV__NUM $84 
a of the driver whose device name is 
specified. The device need not be 0 
| . 
| open. The dev_num returned is 
_ used inthe D_ STATUS, 1 janineiiis 
D CONTROL, and D_ INFO Calls. pointer 
2 
| Required Parameters , 
— result 
dev_name: pointer 
Py This is a pointer to a string in memory containing the device name of the 
_ device whose number is to be returned: the first byte of the string is the 
| number of bytes in the name; the rest are the bytes of the name itself. Note 
_ that this a device name, not a pathname. 
_ dev_num: 1 byte result 


Range: $01..$18 


_ This is the device number of the device specified by dev_name. The name 
of a device can be changed by the System Configuration Program. 


Errors 


$10: DNFERR Device name not found 
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_ 10.1.4 D__INFO Device Call $85 

_ This call returns the device name __INFO $85 
(and optionally, other information) 

_ about the device specified by dev_num. Q ——— 
The device’s character file need not 

_ be open. D_INFO returns identifying 1 
information about the device's 

_ external status and interface to SOS; 2 doe-acannes 
D STATUS returns information pointer 

_ about the internal status of the 3 
device and its driver. 

— . option list 
Required Parameters 5 eae 
dev_num: 1 byte value 6 

_ Range: $01..$18 
This is the device number of the g 

= device whose information is to be eau 


returned, obtained from the 1 
ey GET _DEV_NUMcall. 


unit_num 
result 

dev_type 
result 


2 
dev_name: pointer 5 
_ This is a pointer to a sixteen-byte result 
buffer into which SOS is to store 4 Sunused 
_ the resulting device name: the first 
byte of the buffer is the number of 5 ssial’ blocks 
— bytes in the name; the rest are the result 
bytes of the name itself. 6 
option list: pointer q manut_id 
prem -_ result 
This is a pointer to the optional 8 
parameter list if length is between 
A $00 and $@A; otherwise it is ignored. 9 saisienicnamn 
result 
yy A 


length: 1 byte value 
Range: $00..$0A 


This is the length in bytes of the optional parameter list. It specifies 
which optional parameters are supplied. 
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The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take half 
a parameter, but reduces the length to the next defined value. 


$00 = no optional parameters 

$01 = slot_ num 

$2 = slot_num through unit_num 
$03 = slot_num through dev_type 
$5 = slot_num through sub type 
$07 = slot_num through total_blocks 
$09 = slot_num through manuf _id 
$B = slot_num through version num 


Optional Parameters 


slot_num: 1 byte result 
Range: $00..$04 


This is the slot number of the peripheral slot the device uses. Slot 
numbers $01 through $04 correspond to peripheral slots 1 through 4. Slot 
number $09 indicates the device does not use a peripheral slot. 


unit_num: 1 byte result 
Range: $00..$FF 


This is the unit number of the device. Devices that are bundled together 
into one driver module are assigned unit numbers in ascending sequence, 
beginning with $00. See the Apple I/] SOS Device Driver Writer’s Guide 
for more details. 


This parameter has nothing to do with the logical unit numbers 
that Pascal associates with the devices. 
dev_type: 1 byte result 


Range: $00..$FF 


The dev_type byte, along with the following byte, is used for 
device classification and identification. This field specifies the 
generic family that the device belongs to. 
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The dev_type byte for SOS character devices has the following 
structure: 


Bit 7 is cleared for all character devices. 


Bit 6 (W) is write allowed byte. It must be set for all character devices that 
accept data from the Apple Ill. 


Bit 5 (R) is the read allowed bit. It must be set for all character devices that 
send data to the Apple III. 


Bit 4 is reserved for future use and must always be cleared. 
The dev_type byte for SOS block devices has the following structure: 


ff 6 S 4 3 2 1 0 


W Rem Fmt X X xX xX 


Bit 7 is set for all block devices. 


Bit 6 (W) is write allowed byte. It must be set for all block devices that 
accept data from the Apple III. 


Bit 5 (R) is the removable device bit. It must be set for all block devices that 
use removable storage media, such as floppy-disk drives. 


Bit 4 is set if the driver can also format its device. 


sub type: 1 byte result 

Range: $00..$FF 
The device subtype identifies the specific device within the generic family 
specified in dev_type. 


unused: 1 byte 


SOS Reference Manual 


total_blocks: 2 byte result 
Range: $0000..$FFFF 


If the device is a block device, this parameter indicates the total number of 
blocks it can access. If the device is a character device, this parameter 
returns $0000. The Apple III’s built-in disk drive can access $0118 blocks. 


manuf_id: 2 byte result 
Range: $0000..$FFFF 


The manufacturer identification code uniquely identifies the manufacturer 
of the driver. The currently assigned values are 


$0000 Unknown 
$0901 Apple Computer,|nc. 


version_num: 2 byte result 
Range: $0000..$9999 


This is the version number of the device driver. The format is BCD (binary- 
coded decimal); no hexadecimal digits from $A to $F will appear in this 
result. 


Comments 


The following values for dev_type and sub_type are assigned: 


dev_name dev type sub type 
RS232 printer (PRINTER) $44 $01 
Silentype printer (.SILENTYPE) $41 $02 
Parallel printer (PARALLEL) $41 $03 
Sound port (.AUDIO) $43 $01 
System console (.CONSOLE) $61 $01 
Graphics screen (.GRAFIX) $62 $01 
Onboard RS232 (.RS232) $63 $01 
Parallel card (PARALLEL) $64 $01 
Disk II] (.D1 through .D4) $E1 $01 
ProFile disk (.PROFILE) $D1 $02 
Block device formatter: 

Disk II] (.FMTD1 ... .FMTD4) $11 $01 


a 


7 


Device Calls and Errors 


Please contact the PCS Division Product Support Department of Apple 
Computer, Inc. if you wish to be assigned a dev_type, sub_type, 

manuf _id, or version_num. This will ensure that such codes are unique 
and are known to SOS and future application programs. 


Errors 


$11: BADNUM __ Invalid device number 


10.2 Device Call Errors 


The errors below are generated by SOS device calls; some of them are 
also generated by SOS file calls. Other errors are listed in Appendix D. 
$19: Device not found (DNFERR) 

The device name passed as a parameter to GET__ DEV__NUM isnot that 
of a device that is configured into the system: a device driver with that 
name was not in the SOS.DRIVER file at the time the system was booted, 
or that device driver was inactive. 

$11: Invalid device number (BADDNUM) 

The dev_num parameter does not contain the device number of a device 
configured into the system. 

$20: Invalid request code (BADREQCODE) 

This error is generated only for device requests, made by SOS to a device 
driver, and should never be received as a result of aSOS call. 

$21: Invalid status or control code (BADCTL) 

The control (for D CONTROL) or status (for D_ STATUS) code is not 
supported by the device driver being called. 

$22: Invalid control parameter list (BADCTLPARM) 


The parameter list specified by the control parameter to the 
D CONTROL call is not in the proper format for the control request 
being made. 
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$23: Device not open (NOTOPEN) 

The character device being referenced has not been opened by the file 
OPEN call. 

$25: Resources not available (NORESC) 


The device driver is unable to acquire the system resources (such as 
memory, I/O ports, or interrupts) it needs to operate. This error can also 
occur during a file OPEN call. 


$26: Call not supported on device (BADOP) 
The requested SOS call is not supported by the device. 


$27: I/O error (IOERR) 


The device driver is unable to exchange information with the device, due 
to a bad storage medium or communication line, or some other cause. If 
this happens on a flexible disk, remove and replace the disk, and try again. 


$2B: Device write-protected (NOWRITE) 


The medium in this block device is write-protected. Remove the write- 
protect tab and try again. 


$2E: Disk switched (DISKSW) 


The medium in the block device has been removed and possibly replaced. 
This message is merely a warning, and occurs only the first time the call is 
made: the second time the call is made, it will be executed. 


Errors $30 through $3F are returned by individual device drivers, and 
relate to specific error conditions within those drivers. The error codes 
generated by a device driver are described in the manual describing that 
device driver. 
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11.1 Memory Calls 


These calls are used by SOS to allocate memory for interpreters, as 
explained in section 2.3. 


$49: | REQUEST _SEG — 
$41: FIND SEG 

$42: CHANGE SEG = 
$43: GET SEG INFO | 
$44. GET SEG NUM ~ 
$45: RELEASE SEG 


11.1.1 REQUEST_ SEG 
This call requests the contiguous 
region of memory bounded by the 
base and limit segment addresses. 
A new segment is created if and 
only if no other segment currently 
occupies part or all of the requested 
region of memory. 


Required Parameters 


base: 2 byte value 
Range: $0020..$10FF 


This is the segment address (bank 
followed by page) of the beginning 
of the memory range requested. 


limit: 2 byte value 
Range: $0020..$10FF 
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Memory Call $40 


REQUEST_ SEG $40 


$04 


base 
value 


limit 
value 


seg id 
value 
seg_num 
result 


‘This is the segment address of the end of the memory range requested. 


seg _id: 1 byte value 
Range: $00..$7F 


This is the segment identification code of the requested segment. The 
caller can use this parameter to identify the type of information that the 


segment will contain. 


The highest four bits of the seg_id identify the owner of the segment: 


Seg_id_ range Owner 

$00 to $OF SOS Kernel 
$10 to $1F Interpreter 
$20 to $7F User 


Contents 


System code 
Interpreter data 
User program and data 


The memory system does not check this parameter to ensure that 


it is in the proper range. 
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seg_num: 1 byte result 
Range: $01..$1F 


If the requested segment is available, this parameter returns the 
segment number of the segment granted. This number must be 
used to identify the segment in subsequent calls to 
CHANGE _ SEG, RELEASE SEG, orGET_ SEG _ INFO. 


Comments 


Both the base and limit segment addresses must reside in switchable 
banks $09 through $@E, system bank $@F, or system bank $19. In 
addition, the base address must be less than or equal to the limit 

address. If the base and limit segment address parameters fail to 

meet the above criteria, then the segment will noi be allocated and 

error BADBKPG will be returned. 


The ranges for base and limit are not continuous: these are the 
allowable segment addresses: 


$0020..$009F 
$0120..$019F 


$9E20..$0E9F 
$OFOO..$OF1F 
$10AQ..$10FF 


SOS can keep track of $1F segments 


Errors 


$E0: BADBKPG Invalid segment address (bank/page pair) 
$E1: SEGRQDN Segment request denied 
$E2: SEGTBLFULL Segment table full 


11.1.2 FIND__SEG 


This call searches memory from 
high memory down, until it finds the 
first free space that is pages pages 
long and meets the search 
restrictions in search_mode. If 
such a space is found, it assigns 
this free space to the caller as a 
segment (as in REQUEST SEG), 
returning both the segment number 
and the location in memory of the 
segment. If asegment with the 
specified size is not found, then the 
size of the largest free segment 
which meets the given criterion will 
be returned in pages. In this case, 
however, error SEGRQDN will be 
returned, indicating that the 
segment was not created. 


Required Parameters 


search_mode: 1 byte value 
Range: $00..$02 
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Memory Call $41 


FIND SEG $41 


search_mode 
value 
seg id 
value 


pages 
value/result 


base 
result 


seg num 
result 


This parameter selects one of three constraints to place upon the 


segment search: 


$00: may not cross a 32K bank boundary 
$01: may cross one 32K bank boundary 
$@2: may cross any 32K bank boundary 
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seg id: 1 byte value 
Range: $00..$7F 


This is the segment identification code of the requested segment. The 
caller can use this parameter to identify the type of information that the 
segment will contain. 


The highest four bits of the seg_id identify the owner of the segment: 


Seg id range Owner Contents 


$00 to $OF SOS Kernel System code 
$10 to $1F Interpreter — Interpreter data 
$20 to $7F User User program and data 


The memory system does not check this parameter to ensure that it is in 
the proper range. 


pages: 2 byte value/result 
Range: $0001..$F FFF 


This is the the number of contiguous pages to search for. If no free space 
is found that contains this many pages, then the memory system will 
return in this parameter the size of the largest free space it can find; the 
SEGRQDN error is also generated. A page count of $00 always returns 
error BADPGCNT. 


base: 2 byte result 

Range: $0020..$0E9F 
This is the the segment address of the beginning of the new segment. 
limit: 2 byte result 

Range: $0020..$@E9F 
This is the segment address of the end of the new segment. 
seg num: 1 byte result 

Range: $01..$1F 


This is the the segment number of the segment granted. This number 
must be used to identify the segment in subsequent calls to 
CHANGE_ SEG, RELEASE SEG, orGET_ SEG_ INFO. 
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Comments 


FIND __SEG does not search the system banks $0F and $19. 


The base and limit parameters both return $0000 if the segment is not 
granted; even though pages returns the length of the largest available 
segment, base and limit do not return its location. 


Errors 

$E1: SEGRQDN Segment request denied 

$E2: SEGTBLFULL Segment table full 

$E5: BADSRCHMODE Invalid search mode parameter 
$E7: BADPGCNT Invalid pages parameter ($00) 
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11.1.3 CHANGE_SEG 


This call changes either the base 
or limit segment address of the 
specified segment by adding or 
releasing the number of pages 
specified by the pages parameter. 
If the requested boundary change 
overlaps an adjacent segment or 
the end of the memory, then the 
change request is denied, error 
SEGRQDN is returned, and the 
maximum allowable page count is 
returned in the pages parameter. 


Required Parameters 


seg num: 1 byte value 
Range: $01..$1F 
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Memory Call $42 


CHANGE_ SEG $42 


i) $03 


1 seg num 
value 


5 change_mode 
value 


pages 
value/result 


This is the segment number of the segment to be changed. 


change_mode: 1 byte value 
Range: $00..$03 


The change mode indicates which end (base or limit) of the segment to 
change, and whether to add or release space at that end. 


$00: Release from the base (decrease size) 
$01: Add before the base (increase size) 
(increase size) 
$03: Release from the limit (decrease size) 


$02: Add after the limit 


pages: 2 byte value/result 
Range: $0001..$FFFF 


This is the number of pages to add to or release from the segment. If too 
many pages are added to or removed from the segment, then the segment 
is not changed, and the maximum number of pages that can be added or - 
removed in the requested change_mode is returned in this parameter, 


along with a SEGRQDN error. 


SOS Reference Manual 


Comments 
You cannot move both ends of a segment at once. 


If the segment was granted by FIND. SEG,aCHANGE_ SEG 
operation will not heed the bank-crossing criterion that was used in 
finding the segment. If you request a segment that does not cross a 
bank boundary, then increase it with CHANGE _ SEG, the larger 
segment may cross a bank boundary. 


Errors 


$E1 SEGRQDN Segment request denied 
$E3 BADSEGNUM __ Invalid segment number 
$E6 BADCHGMODE Invalid change mode parameter 
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_ 11.1.4. GET_SEG_INFO Memory Call $43 
— This call returns the beginning and GET_SEG_ INFO $43 

| ending locations, size in pages, and 
_ identification code of the segment Q 

| specified by seg num. 

a 
a value 
Required Parameters ‘ 


seg num: 1 byte value 
-- Range: $01..$1F 


This returns the segment number of 


base 
result 
limit 

result 


Py an existing segment. : 
A base: 2 byte result : 
_ Range: $0020..$109F pages 
| result 
This returns the segment address of 7 
— the beginning of that segment. ; 
result 
am limit: 2 byte result 
Range: $0020..$109F 
my This returns the segment address of the end of that segment. 
- pages: 2 byte result 
oe Range: $0001..$FFFF 
| This returns the number of pages contained by the segment. 
| seg _id: 1 byte result 
— Range: $00..$7F 
_ This returns the identification code of the segment. The highest four bits 
of the seg _id identify the owner of the segment: 
— 
Seg_id_ range Owner Contents 
; $00 to $OF SOS Kernel System code 
_ $10 to $1F Interpreter Interpreter data 
$20 to $7F User User program and data 
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Errors 


$E3: BADSEGNUDN __ Invalid segment number 
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11.1.5 GET_SEG_NUM Memory Call $44 
This call returns the segment GET_SEG_NUM $44 
number of the segment, if any, that 
contains the specified segment Q 
address. 

seg address 
Required Parameters ; MEINE 


seg address: 2 byte value : 
Range: $0020..$109F result 


This is the segment address in 
question. 


seg_num: 1 byte result 
Range: $01..$1F 


This is the segment number of the segment that contains the specified 
segment address. 


Comments 


You may make a subsequent call toGET SEG _INFOwith the resultant 
segment number to determine the ownership of that segment. 


Errors 
SEO: BADBKPG Invalid segment address (bank/page pair) 
$E4: SEGNOTFND Segment not found 
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11.1.6 RELEASE_SEG Memory Call $45 


This call releases the memory RELEASE SEG $45 
occupied by the segment specified 
by seg_num, by removing the 
segment from the segment table. 
The space formerly occupied by 
the released segment is returned to 
free memory. If seg_num equals 
zero, then all nonsystem segments (those with segment identification 
codes greater than $@F) will be released. 


Required Parameters 


seg_num: 1 byte value 
Range: $00..$1F 


This is the segment number of the segment to be released. If seg_num is 
$00, then all segments not owned by SOS are released. 


Errors 


$E3 BADSEGNUM Invalid segment number 
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11.2 Memory Call Errors 


The errors below are generated by SOS memory calls. For other errors, 
see Appendix D. 


$E@: Invalid segment address (BADBKPG) 


The segment address has an invalid bank number, page number, or both. 


$E1: Segment request denied (SEGRQDN) 


No segment can be created that meets the caller's size and boundary 
criteria. 


$E2: Segment table full (SEGTBLFULL) 


SOS can keep track of no more segments: existing segments must be 
released or consolidated if more segments are needed. 


SOS can keep track of $1F segments. 


$E3: Invalid segment number (BADSEGNUM) 


The seg_num passed is not that of a currently existing segment. 


$E4: Segment not found (SEGNOTFND) 


For GET SEG _ NUM, no segment in the system contains the segment 
address specified. 


$E5: Invalid search_mode parameter (BADSRCHMODE) 
For FIND __SEG, the search_mode parameter is invalid (greater than $02). 


$E6: Invalid change_mode parameter (BADCHGMODE) 


For CHANGE _ SEG, the change_mode parameter is invalid (greater 
than $@3). 


$E7: Invalid pages parameter (BADPGCNT) 


The pages parameter is invalid (equal to $00). 
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12.1 Utility Calls 

The following system calls deal with the system clock/calendar, the Ld 

event fence, the analog input ports, and other general system 

resources. Li 
$60: SET FENCE LJ 
$61: GET FENCE 
$62: SET TIME Li 
$63: GET TIME 
$64: GET ANALOG | 
$65: TERMINATE _ 

— 
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— 42.1.1 SET_FENCE Utility Call $60 
—_ This call changes the current value SET__FENCE $60 
of the user event fence to the value 
_ specified in the fence parameter. 0 
— Required Parameters 
am | fence: 1 byte value 
Range: $00..$FF 
Py This parameter contains the new value of the user event fence for the 
= operating system’s event mechanism. Events with priority less than or 
equal to the fence will not be serviced until the fence is lowered. 
Errors 
No errors are possible. 
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_ 12.1.2 GET_FENCE Utility Call $61 
= This call returns the current value of GET_ FENCE $61 

| the user event fence. 
— 0 $01 


Required Parameters 


fence 
come | 
fence: 1 byte result 
Range: $00..$FF 


This parameter returns the current setting of the user event fence. Events 
with priority less than or equal to the fence will not be serviced until the 
fence is lowered. 


— Errors 


am | No errors are possible. 


i 
| 
ig) 

= 
® 
O 
® 
_ 
® 

— 
® 

Oo 

Y) 

O 

WY) 


Utility Calls and Errors 95 


— 
™ 12.13 SET__TIME Utility Call $62 
_ This call sets the system clock to SET_ TIME $62 

the contents of a buffer located at 
_ the specified address. If the system 0 $01 

has no functioning clock, 
- SET_ TIME stores the contents of 1 ' 

the buffer as the last valid time, to rine 
_ be returned on the next 2 

GET_ TIME cail. 

Required Parameters 

time: pointer 
- This is a pointer to an 18-byte buffer containing the current date and time. 
— The information is specified as an 18-byte ASCII string whose format is 
- YY Y Y MM DOD xX H HNN S S X X X 
_ The meaning of each field is as below: 
ry Field Meaning Minimum Maximum 
- YYYY: Year 1900 1999 
_ MM: = Month QO or O1 12 (December) 

DD: Date 00 or 01 28, 30, or 31 
_ X: — Ignored 
| HH: Hour 00 (Midnight) 23 (11:00 p.m.) 
— NN: = Minute ty 59 
SS: | Second 00 59 
_ XXX: — Ignored 
= For example, December 29, 1989, at 9:30 a.m., would be specified by the 
| string “198012290093000000”. 
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Comments 


On input, SOS replaces the first two digits of the year with “19” and 
ignores the day of the week and the millisecond. SOS calculates the day 
from the year, month, and date. 


SOS does not check the the validity of the input data to make sure each 
field is in the proper range. The clock makes several restrictions: it rejects 
any invalid combination of month and date. The clock only accepts dates 
in the range 1..30 if the month is 4, 6, 9, or 11; it only accepts dates in the 
range 1..28 if the month is 2: February 29 is always rejected. 


SET__ TIME attempts to set the hardware clock, whether or not it is 
present and functioning. It also stores the new time in system RAM as the 
last known valid time; this time will be returned by all subsequent 
GET _ TIME calls if the hardware clock is missing or malfunctioning. 

The clock does not roll over the year. 

The format ofthe SET__ TIME string is the same as that ofthe GET TIME 


result, except that SET _ TIME ignores the day of the week and the 
millisecond fields. 


Errors 


No errors are possible. 
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12.1.4 GET__TIME Utility Call $63 
This call reads the time from the GET_ TIME $63 
system clock and returns it to the 
buffer located at the specified 0 $01 
address. If the system has no 
functioning clock, GET TIME 1 ; 

mses hee time 
returns the last known valid time. pointer 

2 

Required Parameters 
time: pointer 


This is a pointer to an 18-byte buffer containing the current date and time. 
The information is specified as an 18-byte ASCII string whose format is 


YYYYMMDDWHHAHNNSSUUU 


The meaning of each field is as below: 


Field Meaning Minimum Maximum 
YYYY: Year 1900 1999 
MM: = Month 00 or 01 12 (December) 
DD: Date 00 or 1 28, 30, or 31 
W: Day 01 (Sunday) 07 (Saturday) 
HH: Hour Q@ (Midnight) 23 (11:00 p.m.) 
NN: — Minute 00 59 
SS: | Second 00 59 
UUU: Millisecond @@@ 999 


For example, Friday, March 21, 1980, at 1:27:41.001 p.m., would be returned 
as “198003216132741001”. 


Comments 


lf the hardware clock is not operational, the utility manager retrieves 
the last known valid time from system RAM. If no last Known valid time 
is stored, GET__ TIME returns a string of eighteen ASCII zeros: 
“Q000DDHOHOHOHOPOBO”. 
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SOS calculates the day of the week from the year, month, and date. 

The clock will only generate dates in the range 1..3@ if the month is 4, 6, 9, 
or 11; it will only generate dates in the range 1..28 if month is 2: February 29 
will never be generated by a system with a functioning clock. A system 
without a functioning clock can return February 29 if that month and date 
have been set byaSET TIME call. 

The clock does not roll over the year. 


You must ensure that the buffer pointed to by time can hold all eighteen 
($12) bytes, to avoid overwriting other data. 


Errors 


No errors are possible. 
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_ 12.1.5 GET_ANALOG Utility Call $64 
_ This call reads the analog and GET_ ANALOG $64 
digital inputs from an Apple III 
_ Joystick connected to port Aor B $92 
on the back of the Apple III. 
| value 
Required Parameters 
joy_mode: 1 byte value és 
— Range: $00..$07 = 
a This parameter specifies the A 
joystick inputs to be read. For each 7 
_ value of joy_mode, the following rasilt 
inputs will be read: 
Py Joy mode Port Buttons/Switches Horizontal Vertical 
Fe $00 B JSQ-B,JStSw = — = 
‘at $01 B JS@-B, JS@-Sw JS@-X — 
$02 B JS@-B, JS@-Sw — JSQ-Y 
= $03 B JS@-B, JSO-Sw JS@-X JSQ-Y 
$04 A JS1-B, JS1-Sw — — 
ny $05 A JS1-B, JS1-Sw JS1-X — 
$06 A JS1-B, JS1-Sw — JS1-Y 
= $07 A JS1-B, JS1-Sw JS1-X JS1-Y 
= The names for these variables are those used in the Apple /// Owner's 
Guide, Appendix C. These eight variables are returned by the 
ae joy_status parameter. 
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joy_status: 4 byte result 
Range: $00000000..$FFFFFFFF 


This 4-byte field is treated as one parameter by SOS. Here we 
subdivide it into four 1-byte fields for clarity; n represents the 
numbers of the joystick (1 or 2) as determined by the joy_mode 
parameter. 


JSn-B: 1 byte result 
Range: $00..$FF 


This digital output returns $00 if the button is off and returns 
$FF if the button is on. 


JSn-Sw: 1 byte result 
Range: $00..$FF 


This digital output returns $0 if the switch is off and returns $FF 
if the switch is on. 


JSn-X: 1 byte result 
Range: $00..$FF 


This analog output returns a value from $00 to $FF 
corresponding to the horizontal position of the joystick. A 
position that was not read (due to the joy_mode parameter) 
returns a byte of $090. 


JSn-Y: 1 byte result 
Range: $00..$FF 


This analog output returns a value from $00 to $FF 
corresponding to the vertical position of the joystick. A position 
that was not read (due to the joy_mode parameter) returns a 
byte of $00. 
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Comments 

An input device other than a joystick can be read, provided (a) it uses the 
same pins for analog and digital inputs, and (b) each pin produces the 
correct signals, as described in the Apple /// Owner's Guide. 


Both buttons of the selected joystick are always read and returned. 


Reading the analog inputs slows down the execution speed of this call 
and should be avoided when unnecessary. 


JSn-B, JSn-Sw, JSn-X, and JSn-Y all return results of $FF if no joystick is 
attached to the port. 


The XNORESFC error will be generated if an attempt is made to read Port 
A and a device driver (such as the Silentype driver) has already claimed 
the use of that port. 


The parm_count is $02, not $5. 


Errors 


$25 XNORESRC_ Resource not available 
$76 BADJMODE Invalid joystick mode 
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12.1.6 TERMINATE 


This call clears memory, clears the 
screen, and displays INSERT 
SYSTEM DISKETTE & REBOOT in 
49-column black-and-white text 
mode on the screen. The system 
then hangs, and waits for the user 
to press CONTROL-RESET 

and reboot. 


Required Parameters 


None 


Comments 
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Utility Call $65 


TERMINATE $65 


call num = $65 
+2 
P parm_list = p 
pointer 
pt+3 


Only the SOS Call Block is shown for this call. Since this call has no 
parameters, the parameter_count is $00. Thus the parameter _list pointer 
must point to a byte containing $09. The most convenient such byte is the 
BRK opcode beginning the TERMINATE call, so this call customarily bites 


its own tail. 


Before issuing a TERMINATE call, the interpreter should close all open 
files. This will ensure that all |1/O buffers are written out, and all file entries 
updated, while the necessary information still exists. 


This call is the recommended way to leave a program. It provides a clean 
exit to a program, and leaves no traces of it in memory for the user’s 
examination. It can be used in conjunction with a copy-protection scheme 
to protect a program from piracy. It also provides a hook that could be 
used to return control to a future command interpreter. 


Errors 


No errors are possible. This is an excellent call for beginners. 
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12.2 Utility Call Errors 

One error can be generated by one of the utility calls; other errors are | 

listed in Appendix D. — 

$76: Invalid Joystick Mode (BADJMODE) al 

The joy_mode parameter is greater than $07. | 
— 
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Version: SOS 1.1, 1.2 and 1.3 


Classification: 
Single-task, configurable, interrupt-driven operating system. 
File system—hierarchical, tree file structure. 


Device-Independent I/O. 


CPU Architecture: 
Address enhanced 6592 instruction set. 
Supports both bank-switched and enhanced indirect addressing. 
Separate execution environments for user and SOS including 
private zero and stack pages. 

System Calls: 


Based on 6502 BRK instruction, pointer, and value parameter 
types. 


Error codes returned via A register. 
All other CPU registers preserved upon return. 


Optional parameter lists for future expansion. 


File Management System: 
Hierarchical file structure. 
Pathname prefix facility. 


Byte-oriented file access to both directory/user files and device 
files. 


Dynamic, non-contiguous file allocation on block devices. 
Automatic buffering (Current index block and data block). 
Dynamic memory allocation of file buffers. 

Block size (512 bytes). 

File protection: rename/destroy/read/write access attributes. 


File level assignment on Open. 
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Automatic date/time stamping of files. 
my Automatic volume logging/swapping, supported by system 
_— message center. 
Multiple volumes per block device can be “open” simultaneously. 
- Sparse file capability: 
= maximum number of active volumes = 8 
_ maximum disk size = 32 Mbytes 
maximum user file size = 16 Mbytes 
a maximum file entries in volume directory = 51 
ey maximum file entries in a subdirectory = 1663 
—_— file names — maximum 15 characters 
pathnames — maximum 128 characters 
a File system calls: 
| CREATE READ 
—_ DESTROY WRITE 
RENAME CLOSE 
ry SET FILE INFO FLUSH 
ry GET FILE INFO SET MARK 
~_ VOLUME GET MARK 
SET PREFIX SET EOF 
- GET PREFIX GET _EOF 
| OPEN SET LEVEL 
—_ NEWLINE GET LEVEL 
mas Device Management System: 
Block and character device classes. 
Py Standardized interface for block and for character devices. 
a | All devices are named and configurable. 
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Support for synchronous, interrupt, and DMA-based I/O. = 
maximum number of devices = 24 _ 
maximum number of block devices = 12 LJ 

Device system calls: ) 
GET _DEV_NUM D_ STATUS 
D_ INFO D CONTROL | — 

Memory/Buffer Management System: a 

All memory allocated as segments. LJ 

Supports maximum of 512 Kbytes RAM. 

System buffers allocated and released dynamically. = 

System buffer checksum routine for data integrity. _ 

Memory system calls: Li 
REQUEST SEG GET SEG_INFO 
FIND SEG GET SEG NUM _ 
CHANGE_ SEG REL SEG — 

Additional System Functions: — 

System clock/calendar Li 

(year/month/day/weekday/hour/minute/second/ms). 

Joysticks: reads X and Y axes, pushbutton, and switch. — 

TERMINATE call provides clean program termination and clears LJ 

memory. 

System calls: = 
SET TIME TERMINATE Lj 
GET_ TIME GET ANALOG 

= 
LJ 
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Interrupt Management System: 
Receives hardware interrupts (IRQ, NMI) and system calls (BRK). 
Hardware resource allocation and deallocation. 


Dispatches to driver interrupt handlers. 


Event Management System: 
Priority-based event signaling. 
Event handlers preempted by higher priority events. 
Events with equal priorities process FIFO. 
Event fence delays events with priority less than fence. 
Event system calls: 
SET FENCE GET FENCE 


System Configuration: 


Menu-driven system-configuration editor (System Configuration 
Program). 


Can add, remove, and modify drivers and can select the 
keyboard-layout and system-character-set tables. 
Standard Device Drivers: 

Floppy disk (.D1, .D2, .D3, .D4) 
143,360 bytes (formatted) per volume. 
Automatically reports mounting of a new volume. 
Built into SOS kernel. 

Console (.CONSOLE) 
Interrupt-driven keyboard (supports type-ahead). 
Configurable keyboard-layout table (via SCP). 
Raw-keystroke and no-wait input modes. 
Event handler supports anykey and attention character. 


Optional screen echoing. 
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Console control modes: 
video on/off —_ 
flush type-ahead buffer 
suspend screen output —_ 
display control characters 
flush screen output _— 
Cursor positioning commands. LJ 
Viewport set, clear, save, and restore commands. | 


Horizontal and vertical scrolling. 


Text modes: 24 x 80 and 24 x 49 B&W and 24 x 40 color a 
(normal and inverse). 


Configurable system character set table (via SCP). 


Character set can be changed under program control at — 
any time. 


Screen read command. 
Graphics (.GRAFIX) | 


Displays graphical and textual information 


simultaneously. aad 
Graphics modes: _ 
560 x 192 and 280 x 192 in B&W video. | 
280 x 192 and 140 x 192 in 16 colors. — 
Point-plotting and line-drawing commands using graphics = 
viewport and pen. 
Raster block picture operations. — 
Color operator table, controls color overwrite. ‘= 
Transfer modes allow binary operations on the drawing 
color and the current screen color. — 
Allows use of either the system character set or an 
alternate character set to display ASCII text on the _ 
screen. 
Single or dual graphics screens. 
—_ 
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=| 
— General purpose communications (.RS232) 
| RS-232-C interface. 
ry Configurable data rates from 110 to 9600 baud. 
= Configurable protocols, including XON/XOFF, ETX/ACK, 
and ENQ/ACK. 
- Interrupt-driven, buffered, bi-directional data transfer. 
_ Hardware handshaking option. 
Serial printer (.PRINTER) 
a 
RS-232-C interface. 
ey Configurable data rates from 119 to 9600 baud. 
— Interrupt-driven and buffered (output only). 
Hardware handshaking option. 
ry 
Audio (.AUDIO) 
| 64 volume levels. 
- Produces tones from 31 to 589@ Hz (over 7 octaves). 
Duration range from @ to 5 sec (increments of 1/60 sec). 
oe | 
a | 
ae 
| 
a | 
a | 
a | 
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ExerSOS is a interactive BASIC program that lets you make SOS calls 
from the keyboard without writing a special assembly-language 
program to test each call. It is intended to let you try out calls to see 
how they work. ExerSOS lets you choose a call from a menu, then 
prompts you for each of the call’s input parameters, and gives you 

the correct output parameters or error message. 


B.1 Using ExerSOS 


To use ExerSOS, insert the ExerSOS disk into the built-in drive and 
press CONTROL-RESET. After the introductory displays you will 
see the Main Menu. 


B.1.1_ Choosing Calls and Other Functions 


The Main Menu presents you with a choice of functions. Typing @ 
will EXIT ExerSOS. The first 35 of these functions are SOS calls 
(listed below by type). The remainder are special functions 
available within ExerSOS. The full list of functions is 


File Calls: 


$C@: CREATE 

$C1: DESTROY 

$C2: RENAME 

$C3: SET FILE INFO 
$C4: GET FILE INFO 
$C5: VOLUME 

$C6: SET PREFIX 
$C7: GET PREFIX 
$C8: OPEN 

$C9: NEWLINE 

$CA: READ 

$CB: WRITE 

$CC: CLOSE 

$CD: FLUSH 
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$CE: 
SCF: 
$D90: 
$D1: 
$D2: 
$D3: 


Device Calls: 


$82: 
$83: 
$84: 
$85: 


Memory Calls: 


Utility Calls: 


$60: 
$61: 
$62: 
$63: 
$64: 


SET MARK 
GET MARK 
SET EOF 
GET EOF 
SET LEVEL 
GET LEVEL 


D STATUS 
D__CONTROL 
GET _DEV_NUM 
D_INFO 


REQUEST_ SEG 
FIND. SEG 
CHANGE_ SEG 
GET _SEG_INFO 
GET SEG NUM 
RELEASE SEG 


SET FENCE 
GET FENCE 
SET TIME 
GET_ TIME 
GET ANALOG 


ExerSOS Utilities: 


Display Directory 

Display Open Files 

Display Active Memory Segments 
Display/Edit Contents of Data Buffer 


ExerSOS 
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B.1.2 Input Parameters 


When you select a SOS call from the Main Menu, the display is replaced 
by a split-screen menu showing the name of the call at the top. The left 
half of the screen is used for typing input parameters to the call; the right 
is used to show the resultant SOS call error and any output parameters. 
You will then be prompted for each input parameter, following the 
description of the call in the SOS Manual. If you wish to return to the Main 
Menu, type a backslash (\) and press RETURN. 


All parameters have the same names as in this manual, and appear in 
the same order as in the description of the SOS call in Volume 2. Pointer 
parameters, however, are omitted, as all values and results are passed 
interactively, rather than by building a table in memory and passing its 
address. 


In some cases, a range of legal values is displayed; if your entry falls 
outside that range, you will be prompted again. For example, the first 
is 


If you respond to this with an out-of-range value, the prompt will be 
repeated. 


You may also type data in hexadecimal by preceeding a value with a 
dollar sign ($). Some input fields have a fixed dollar sign: these fields 


AL 


< x 


When typing an input parameter, you can use the ESCAPE key to edit 
the input, as in BASIC. 


Several SOS calls employ an optional parameter list along with a length 
parameter. For those calls, ExerSOS asks you for the length and 
selectively prompts or displays information as requested. 
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B.2 The Data Buffer 


ExerSOS maintains two buffers you should be aware of: the data buffer 
and the string buffer. ExerSOS alone locates the 16K data buffer in 
memory. All |/O operations (READ, WRITE) use the data buffer. Hence, 
a READ call followed by a WRITE call will transfer bytes from one file 
to another. 


In order to ensure the return of this 16K space to the system, 
always exit ExerSOS through the Main Menu, never by typing 
CONTROL-C. If you should accidentally exit ExerSOS, reboot 
by pressing CONTROL-RESET. 


B.2.1 Editing the Data Buffer 


The Display/Edit function allows you to select any of the 64 256-byte 
pages of memory occupied by the data buffer, and displays that page in 
hex with the ASCII equivalents on the right side of the screen. You are 
then placed in Edit mode with the cursor (denoted by matching “[..]”) 
positioned in the upper-right corner. You can move the cursor through 
the use of the four arrow keys. 


You can alter the contents of a byte by typing a hex digit, (that is, @..9, 
A..F, a..f). Note that as you do so, the value you type is placed in the 
low-order nibble of the target byte, and the value that was in the low-order 
nibble moves to the high-order nibble. You may terminate the input to a 
byte by pressing RETURN, which accepts the new value, or ESCAPE, 
which restores the original value. 


If you press ESCAPE while you are in the cursor-positioning phase, you 
exit from Edit mode and have the choice of returning to the Main Menu 
or displaying another page of the buffer. 
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B.3 The String Buffer 


The string buffer is used by many of the calls as temporary storage any 
time a pathname or device name is passed into or out of aSOS call. 
Additionally, the D_ STATUS and D__ CONTROL calls use the string 
buffer for the STATUS LIST and CONTROL __LIST, respectively. 


The following SOS calls require some further user input: 


D_ STATUS 


In addition to the SOS-required input parameters, ExerSOS 
prompts you for two more items. The first prompt, 


lets you initialize the string buffer by typing Y, or leave its current 
contents intact by typing N. Usually, you will initialize it, to make 
sure no garbage from a previous call obscures your results. 
However, in some cases, you may wish to make a status call, then 
change something with a control call, then check the buffer with 
a status call again: in such a case do not initialize the buffer. 


The second prompt, 


asks you how many bytes of the string buffer you wish to see. if 
you specify more bytes than are in the status list, the remaining 
bytes will be either zeros or garbage, depending on your response 
to the “Initialize?” prompt. 


D__CONTROL 


After you specify the dev_num and control_code, ExerSOS allows 
you to specify the control list from either of two places. If you 
type a “Q” to the “Length of input” prompt, the call is made from 
the current value of the string buffer. If you respond to the prompt 
with a value larger than @, you are prompted for each byte of 

the control list. The resultant string is moved into the string buffer. 
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B.4 Leaving ExerSOS 


To leave ExerSOS, return to the Main Menu and type @. You will be asked 
to confirm your intention: type Y to exit (any other reply will return you to 
the Main Menu). ExerSOS will drop into BASIC, and you will be able to run 
another BASIC program, or reboot by pressing CONTROL-RESET. If you 
leave ExerSOS inadvertently, as by typing CONTROL-C, you should 
reboot. If you try to RUN the program without rebooting, you will have 
lost the 16K space allocated to the data buffer. 
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Makelinterp is a program that takes an assembly-language code file 


produced by the Apple III Pascal Assembler and converts it to the proper 


format for a bootable SOS.INTERP file. If you are writing an interpreter, 
this makes it unnecessary for you to know the details of interpreter file 
format, and protects you from future changes in this format. 


To use Makelnterp, boot Pascal and insert the ExerSOS disk into, say, 
.D2. Now execute (that is, type X) 


.D2/MAKEINTERP.CODE 


Then type the input pathname, the name of the interpreter code file, for 
example, 


.D2/INTERP.CODE 
and the output pathname, say, 


.D2/SOS.INTERP 


As the disk spins, you see this message displayed: 


When the conversion is complete, Makelnterp displays the message 


and returns you to the Pascal command line. 


All pathnames must be complete, with suffix. If you type any invalid input, 


you will have to execute the program again. 
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SOS detects two types of errors: 


e Non-fatal SOS errors, occurring during a SOS call, that are 
detected and flagged; 


e Fatal SOS errors, occurring during a SOS call or interrupt 
sequence, that signal such a substantial irregularity that the 
system cannot continue to operate. 


In addition, the SOS bootstrap loader detects bootstrap errors, which 
occur only when the system is starting up. 


The reporting mechanism for non-fatal SOS errors is discussed in 
Volume 1, section 8.4. The error code is returned in the accumulator after 
a SOS call: an error code of $@@ means no error was encountered in 

the call. The error code is normally used by the interpreter to display a 
message to the user, to repeat an operation, or to take some other action. 


Bootstrap errors and fatal errors occur when an error condition is so 
critical that no recovery is possible. These errors cause their own 

messages to be displayed on the screen, as no interpreter is in place 
to interpret them. These errors are discussed in detail in section D.3. 


D.1 Non-Fatal SOS Errors 


Explanations of the general system errors are given in section 8.4 of 
Volume 1. Explanations of the other non-fatal system errors are given 
in Volume 2. The list below, numerically ordered, is for easy reference. 
Three things are listed for each error: the error number, a suggested 
name for the assembly-language routine handling the error, anda 
suggested error message for the interpreter to display on the screen. 


D.1.1 General SOS Errors 


(See section 8.4) 


$01: BADSCNUM Invalid SOS call number 

$92: BADCZPAGE __ Invalid caller zero page 

$03: BADXBYTE Invalid indirect pointer X-byte 
$04: BADSCPCNT __ Invalid SOS call parameter count 
$05: BADSCBNDS SOS call pointer out of bounds 
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D.1.2 Device Call Errors 


(See section 19.2) 


$10: DNFERR 

$11: BADDNUM 
$20: BADREQCODE 
$21: BADCTLCODE 
$22: BADCTLPARM 
$23: NOTOPEN 

$25: NORESRC 

$26: BADOP 

$27: IOERROR 

$2B: NOWRITE 

$2E: DISKSW 
$30..$3F: 


Device not found 

Invalid device number 
Invalid request code 

Invalid status or control code 
Invalid control parameter list 
Device not open 

Resources not available 
Invalid operation 

I/O error 

Device write-protected 

Disk switched 
Device-specific errors 


D.1.3 File Call Errors 


(See section 9.2) 


$49: BADPATH 
$41: CFCBFULL 
$42: FCBFULL 
$43: BADREFNUM 
$44: PATHNOTFND 
$45: VNFERR 

$46: FNFERR 

$47: DUPERR 

$48: OVRERR 

$49: DIRFULL 
$4A: CPTERR 
$4B: TYPERR 
$4C: EOFERR 
$4D: POSNERR 
$4E: ACCSERR 
$4F: BTSERR 

$50: FILBUSY 

$51: DIRERR 

$52: NOTSOS 

$53: BADLSTCNT 
$55: BUFTBLFULL 


Invalid pathname syntax 
Character File Control Block full 
Block File or Volume Control Block full 
Invalid file reference number 
Path not found 

Volume not found 

File not found 

Duplicate file name 

Overrun on volume 

Directory full 

Incompatible file format 
Unsupported storage type 
End of file would be exceeded 
Position out of range 

Access not allowed 

Buffer too small 

File busy 

Directory error 

Not a SOS volume 

Length parameter invalid 
Buffer table full 
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$56: BADSYSBUF Invalid system buffer parameter 


$57: DUPVOL Duplicate volume 
$58: NOTBLKDEV Not a block device 
$59: LVLERR Invalid level 


$5A: BITMAPADDR __ Invalid bit map address 


D.1.4 Utility Call Errors 


(See section 12.2) 


$70: BADJOYMODE __ Invalid joy_mode parameter 


D.1.5 Memory Call Errors 


(See section 19.2) 

$E0: BADBKPG Invalid segment address 
$E1: SEGRQDN Segment request denied 
SE2: SEGTBLFULL Segment table full 

$E3: BADSEGNUM Invalid segment number 
$E4: SEGNOTFND Segment not found 


$E5: BADSRCHMODE __ Invalid search_mode parameter 
$£6: BADCHGMODE Invalid change_mode parameter 
$E7: BADPGCOUNT Invalid pages parameter 


D.2 Fatal SOS Errors 


If SOS encounters an internal error from which it cannot recover, it 
displays an error message (including the code number of the error that 
occurred) on the screen, beeps the speaker, and hangs. The only 
recovery possible is to reboot. 


The fatal error codes and conditions are listed below. The phrase 
following the number is a convenient name for the error, but no 
interpreter will be able to display it to the user, as SOS will not be 
around to help. 


Error Messages 


$61: Invalid BRK (BADBRK) 


A BRK software interrupt was encountered within SOS. As SOS is not 
reentrant, it is not allowed to make SOS calls to itself; making such a call 
is an unrecoverable error and means that the memory region containing 
SOS has been scrambled. 

$62: Invalid interrupt (BADINT) 


An interrupt occurred that cannot be acknowledged by SOS. The 65@2’s 
IRQ or NMI line was pulled down, but either polling did not reveal the 
device that performed the interrupt, or no device driver had claimed that 
interrupt. 

$64: Invalid NMI (NMIHANG) 


A request was made for SOS to lock the RESET/NMI key, but a device 

is currently attempting to perform a NMI interrupt. If the interrupt is not 
granted and handled within a short time after the request to lock NMI was 
made, this error will occur. 

$85: Event queue overflow (EVQOVEFL) 

More events (See Chapter 6) have occurred than have been handled. 
Possibly the event fence is set too high, and few events are being handled. 
$06: SOS stack overflow (STKOVFL) 

The SOS stack has been pushed to more than 256 bytes, and the data 

at the bottom of the stack have been overwritten. 

$07: Invalid control or status request (BADSYSCALL) 


The device system has detected an invalid control or status request. 


$08: Too many drivers (MCTOVEFL) 


Too many device drivers have been created for SOS to keep track of. 


$89: Memory too small (MEM2SML) 


The Apple III’s memory is too small for SOS to operate in; that is, less 
than 128K bytes. 
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$0A: Buffer Control Block damaged (VCBERR) 


The file system’s Buffer Control Block has been damaged due to a 
memory failure. 


$B: File Control Block damaged (FCBERR) 


The file system’s File Control Block has been damaged due to a 
memory failure. 


$8C: Invalid allocation blocks (ALCERR) 


Allocation blocks are invalid. 


$0E: Pathname too long (TOOLONG) 


A pathname supplied or internally generated contains more than 256 
characters. This can result from concatenating a long prefix to a long 
filename. 


$6F: Invalid buffer number (BADBUFNUM) 


An internal buffer allocation request has supplied an invalid buffer 
number. 


$10: Invalid buffer size (BADBUFSIZ) 


An internal buffer allocation request has supplied an invalid buffer size. 


D.3 Bootstrap Errors 


If an error occurs during the bootstrap operation, an error message is 
displayed (in uppercase inverse characters) in the middle of the video 
screen, the speaker beeps, and the system hangs. Bootstrap errors are 
not SOS errors, as they occur before SOS has started running: for this 
reason, they are not numbered. Any bootstrap error is a fatal error: you 
must insert a proper boot diskette, then hold down the CONTROL key 
and press the RESET button to reboot. 


Error Messages 


The following errors can be produced during a bootstrap operation: 


DRIVER FILE NOT FOUND 


There is no file named SOS.DRIVER listed in the volume directory of the 
boot disk. SOS cannot operate without device drivers, and the drivers 
must be stored in a file with this name in the volume directory of the disk. 


DRIVER FILE TOO LARGE 


The SOS.DRIVER file is too large to fit into the system’s memory along 
with the interpreter. Use the System Configuration Program to remove 
some drivers from this file. 


EMPTY DRIVER FILE 

The SOS.DRIVER file contains no device drivers. SOS requires at least 
one device driver, .CONSOLE, to operate. 

INCOMPATIBLE INTERPRETER 


The interpreter is either too large or specifies a loading location that 
conflicts with SOS. This error usually occurs when trying to load an older 
interpreter with a newer version of SOS. 


INTERPRETER FILE NOT FOUND 


There is no file named SOS.INTERP listed in the volume directory of the 
boot disk. SOS cannot operate without an interpreter, and the interpreter 
must be stored in a file with this name, in the volume directory of the disk. 


INVALID DRIVER FILE 


The SOS.DRIVER file is not in the proper format for a driver file. Make 
sure that the file was created by the System Configuration Program or 
obtained from a valid Apple III boot disk. 


I/O ERROR 


The loader encountered an I/O error while trying to read the kernel, 
interpreter, or driver file from the disk in the Apple III's internal disk drive. 
Make sure the correct disk is properly inserted in that drive. 


SOS Reference Manual 


KERNEL FILE NOT FOUND 


No file named SOS.KERNEL is listed in the volume directory of the boot 
disk. The files SOS.KERNEL, SOS.INTERP, and SOS.DRIVER must all be 
present in the volume directory of a disk to be booted. 


ROM ERROR: PLEASE NOTIFY YOUR DEALER 


Your Apple II] contains an older version of the bootstrap ROM that is not 
supported by this version of SOS. Your Apple dealer should be able to 
replace the ROM at no cost. If you receive this message, please contact 
your dealer or nearest Apple Service Center. 


TOO MANY BLOCK DEVICES 


The SOS.DRIVER file contains too many device drivers for block devices. 
Use the System Configuration Program to remove some of the block 
device drivers from this file. 


TOO MANY DEVICES 


The SOS.DRIVER file, while small enough to fit into memory, contains 
too many device drivers for SOS to keep track of. Use the System 
Configuration Program to remove some drivers from this file. 
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Data Formats of Assembly-Language 
Code Files 


E.1 Code File Organization 
E.2 The Segment Dictionary 
E.3 The Code Part of a Code File 
E.3.1 The Procedure Dictionary 
E.3.2 Procedures 
E.3.3 Assembly-Language Procedure Attribute Tables 
E.3.4 Relocation Tables 
E.3.4.1 Base-Relative Relocation Table 
E.3.4.2 Segment-Relative Relocation Table 
E.3.4.3 Procedure-Relative Relocation Table 
E.3.4.4 Interpreter-Relative Relocation Table 


SOS Reference Manual 


Interpreters can load additional code modules. When you write an 
interpreter, you may want to make these code modules relocatable. 
This appendix describes the relocation information generated by the 
Apple IIl Pascal Assembler. 


Appendix E is derived from the Apple //! Pascal Technical Reference 
Manual. Read that manual if you want more detailed information. 


Most of the information about assembly-language code files described 

in the Apple I/l Pascal Technical Reference Manual is addressed to Pascal 
programmers. However, if you want to use Pascal Assembler code files 
when you write an interpreter, you need to deal with only two general 
areas: the overall organization of the code file, and the data structures 
generated for various psuedo-opcodes by the Pascal Assembler. 


E.1 Code File Organization 


An assembly-language code file consists of a segment dictionary anda 
code part, as shown in Figure E-1: 
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segment 


block 0 dictionary 


block 1 


first and 
only code 
segment 


linker 


Figure E-1. An Assembly-Language Code File 


The first block of a code file generated by the Pascal Assembler is in the 
standard format for block @ of a Pascal code file; this block is called the 
segment dictionary. The remaining blocks of the file constitute the code 
part of the code file, which is a single code segment in this kind of file. The 
code part is followed by linker information: in an assembly-language code 
file, this information is unused. 


Be especially careful in reading this section: words (two bytes of 


data) are used as well as bytes. Be sure you know which type 
each number refers to. 
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E.2 The Segment Dictionary 


Since the code part is a single segment, most of the information in the 
segment dictionary is unused. Figure E-2 shows the information that is 
used. 


low addresses 


high byte low byte 
byte 1 byte 0 word 0 
unused 
byte 3 byte 2 word 1 
CODEADDR = 1 
byte 5 (relative block number) pyle 4 word 2 
(segment 1) 
CODELENG 
byte 7 (in bytes) byte 6 word 3 


unused 
byte 512 | | byte 511 word 255 


high addresses 
Figure E-2. A Segment Dictionary 


Two 2-byte fields in this block are relevant when you write a module 
loader. The first starts at byte 4 and is the starting block number 

(relative to the beginning of the file) of the code generated by the Pascal 
Assembler; call this CODEADDR, because that is the field name in the 
Pascal declaration. The second starts at byte 6 and is the length, in bytes, 
of the code; call it CODELENG, for the same reason. 


Your loading routine should begin loading at the relative block number 
(usually 1) indicated by CODEADDR, and should load the number of 
bytes indicated by CODELENG. 


— 
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E.3 The Code Part ofa Code File 


ei 
a | Following the segment dictionary is the code part, which contains the 
procedure dictionary and the procedures themselves. This is 
ae diagrammed in Figure E-3. 
| high addresses 
high byte low byte 
Py nyle number of ment eye 
CODELENG -1 oe ee CODELENG - 2 
procedures =n number = 1 
| 
pointer to procedure 1 
| 
pointer to procedure 2 
ce | 
more pointers 
" _ A... 
a | 
attribute 
table 
a | procedure 1 
(highest procedure) 
Py 
el attribute 
table procedure n 
| (lowest 
| procedure) 
Pe 
me | more procedures 
a | attribute 
table 
-_ procedure 2 
a 
| byte 1 byte 0 
low addresses 
az | 
— Figure E-3. The Code Part of a Code File 


SOS Reference Manual 


E.3.1 The Procedure Dictionary 


The low byte of the last word of the precedure dictionary is at the address 
CODELENG-2; the structure grows down toward lower addresses, as 
shown in Figure E-3. To decipher the structure, look at the word whose 
location is calculated by CODEADDR * 512 + CODELENG-2. The low 
byte should contain 1. The high byte tells you the number of procedures 
in the code file. Each use of the psuedo-opcodes .PROC or .FUNC 
increments this number. Below this word is a sequence of words that 
contain self-relative pointers to the last word of each procedure in the 
code file. 


A self-relative pointer contains the absolute distance, in bytes, between 
the low byte of the pointer and the low byte of the word to which it points. 
To find the address referred to by a self-relative pointer, subtract the value 
of the pointer from the address of its location. 


The number of a procedure is an index into the procedure dictionary: 
the nth word in the dictionary (counting down from higher addresses) 
contains a pointer to the top (high address) of the code of procedure 
number n. As @ is not a valid procedure number, the @th word of the 
dictionary is used to store a Pascal-specific descriptor (usually 1) and 
the number of procedures in the code file (as described above). 


E.3.2 Procedures 


Each procedure consists of two parts: the procedure code, and the 
procedure attribute table. The procedure code is contained in the lower 
portion of the procedure and grows upward toward the higher 
addresses. 


F.3.3 Assembly-Language Procedure 
Attribute Tables 


A precedure’s attribute table provides information needed to execute 
the procedure. Procedure attribute tables are pointed to by entries 
in the procedure dictionary of each code file. 


Data Formats of Assembly-Language Code Files 


The format of the attribute table of an assembly-language procedure 
is illustrated in Figure E-4. 


The other type of attribute table is described in the Apple /// Pascal 
Technical Reference Manual. 


high addresses 
high byte low byte 


RELOCSEG PROCEDURE 
NUMBER NUMBER = 0 


ENTER IC (pointer to 
start of procedure code) 


number of pointers (n 


base-relative 
relocation table 
(rn self-relative pointers) 


number of pointers (m 


segment-relative 
relocation table 


(m self-relative pointers) 


number of pointers (p 


self-relative 
relocation table 
(p self-relative pointers) 


number of pointers (q 


interpreter-relative 
relocation table 
(q self-relative pointers) 


low addresses 


Figure E-4. An Assembly-Language Procedure Attribute Table 
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The highest word in the attribute table of an assembly-language 
procedure always has @ in its PROCEDURE NUMBER field. This @ 

can be used as a flag to indicate to your loading routine that relocation 
references may need changing to agree with the other information 

in the attribute table. The RELOCSEG NUMBER field must contain @. 


The second-highest word of the attribute table is the ENTER IC field: a 
self-relative pointer to the first executable instruction of the procedure. 
Following this are four relocation tables; from high address to low 
address, they are base-relative, segment-relative, procedure-relative, 
and interpreter-relative. 


E.3.4 Relocation Tables 


A relocation table is a sequence of records that contain information 
necessary to relocate any relocatable addresses used by code within the 
procedure. These addresses must be relocated whenever the code file 
containing the procedure is loaded into or moved within memory. 


The format of all four relocation tables is the same: the highest word 

of each table specifies the number of entries (possibly @) that follow 

at the lower addresses in the table. The remainder of each table contains 
the one-word self-relative pointers to locations in the procedure code 
that must be changed by the addition of the appropriate relative 
relocation constant, which is Known to your interpreter when the code 

is loaded. 


E.3.4.1 Base-Relative Relocation Table 


Every reference to a label associated with the psuedo-opcodes 
PUBLIC and .PRIVATE generates an entry into this table. In the Pascal 
environment, these opcodes flag references to data global to the Pascal 
program. 
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_ E.3.4.2 Segment-Relative Relocation Table 
— References to labels associated with .REF generate segment-relative 
relocation entries. The offsets in this table are relative to the beginning 
- of the code portion of the code file: the address of the lowest byte of 
the code module is added to each of the addresses pointed to in the 
os relocation table. Additionally, references to .PROC or .FUNC names 
generate entries into this table. 
E.3.4.3 Procedure-Relative Relocation Table 
i. 
Addresses pointed to by the procedure-relative relocation table must 
-_ be relocated relative to the lowest address of the procedure. The address 
of the lowest byte in the procedure must be added to the contents of 
— the words pointed to in the relocation table. The relevant Assembler 
directives are .BYTE, .WORD, .BLOCK, and .ASCII. Additionally, any 
= non-relative reference (that is, JMP or LDA, but not BNE or BCS) 
generates an entry into this table. 
_ E.3.4.4 Interpreter-Relative Relocation Table 
_ Entries into this table are generated by references to labels defined 
by the .INTERP psuedo-opcode. The Pascal System uses this to index 
_ into a jump table in the interpreter. 
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interpreter, executing 10 
part ofacode file 119, 121, 
[132], [135] 
segments, executing 27 
sharing 44 
procedure [136] 
code length 120 
CODEADDR_ [134] 
CODELENG [134] 
colon 15 
command interpreter [103] 
commoncode 44 
common file structure 3 
common foundation for 
software 3 
defined 2 
communicating with the 
device 42 
comparing two pointers 37-38 
compatibility with future 
versions 18 
conditions for enhanced indirect 
addressing 31 
configuration block 43 
alter 46 
DIB 483 
conflicts 
between interrupts 104 
with zero page 16 
.CONSOLE 66, 105, 108, 125, 
[109] 
console 40 
constant, relocation [138] 
control 
block, file 64 
flowof 27 
transfer 28 
CONTROL-C_ [117] 
CONTROL-RESET [117] 
control code [63] 
$01, character device [64] 
$02, character device [64] 


control list [63] 
conversions 32 
copy-protection [103] 
copying sparse files 98 
CPTERR [55] 
CPU 104 
CREATE 68, 69, 90, 98, [3-6] 
Creating interpreter files 143 
creation date andtime 64, 81, 84, 
88, 89-90 

field 89-90 
current 

bank 12 

direct pointers to 156 
directory 62 

position marker 51 
current-bank 

address 12, 38 

form 13 
cylinders 77 
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.D1 [109] 
.D2 [109] 
.D3 [109] 
.D4 [109] 
D CONTROL 45, 47, 108, 125, 
128, [63-64], [118] 
D_ INFO 48, 45, 47, [67-71] 
D STATUS 45, 46, [59-61], [118] 
data 
access 10, 27, 29-32 
bank-switching for 30 
and buffer storage 19 
block 93,95, 96 
buffer 50, [117] 
editing [117] 
formats of relocatable 
assembly-language code 
files 146 
infree memory 30 
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data block 99 logical 40 ST 
data buffer [35], [37] block 53 | 
date and time managementcalls 5 _ | 
creation 64,81, 84, 88, 89-90 multiple logical 54 | 
format 90 name(s) 41-42, 44, 50, 55, 60 all 
last mod 64, 88, 89-90, [14], illegal 42 | 
[19] legal 42 S| 
decimal numbers xix syntax 42 
decimal point xix number 44 = | 
DESTROY 68, 69, [7-8] Operationson 45-46 | 
destroy-enable bit [12], [18] output 40 = 
detecting anevent 105 peripheral 8, 104 | 
dev name 43, 60, [23], [65], [67] physical 40 — 
dev num 48, [59], [63], [65], [67] random-access 7 | 
dev type 44, 45, [68] removinga 46 = 
device(s) 8, 40-42 requests 50 | | 
addinga 46 sequential-access 7 = | 
block 8,40 status information 45 | 
call(s) 46-47 subtype 44 | 
errors 160, [125] changing 46 ae | 
Changing name of 46 type 44 — 
Character 8, 40 changing 46 
communicating with the 42 device-independent I/O 67 = | 
control information 45 DIB | 
correspondence configuration block 48 = 
logical/physical 54 header 43 | 
special cases of 54 dictionary 8 | 
defined as logical device 54 current 62 aa. | 
driver(s) 5,41, 77, 104, 107, entry 62 = 
108, 125 procedure [135], [136] | 
asynchronous operation of error (DIRERR) [55] Lu 
104 file 57-58 
environment 20-21 format(s) 78-92 
errors, individual 160 header 78 


graphics 16 
standard [109-111] 
memory placement 21 
independence 7,67 
information 43-44 
block (DIB) 43 

input 40 


storage formats 76 
segment [132], [134] 
volume 54,57, 78 

digit(s) 42,56 
hexadecimal 12 
direct pointer 154,155 
to S-bank locations 155 


directory file, readinga 91-92 


BHERE EEE & 


DIRERR [55] 
DIRFULL [55] 
disarming events 108 
Disk III driver 41 
disk drives 40 
disk, flexible 42, 77,93 
DISKSW_ [72] 
dispatching routine 28 
displacement [43], [48] 
Display/Edit function [117] 
DNFERR_ [71] 
dollar signs  xviil, xix 
driver 
device See device driver 
module 41 
placement of 44 
DRIVER FILE NOT FOUND 
DRIVER FILE TOO LARGE 
DUPERR [54] 
DUPVOL [56] 


[129] 
[129] 


E 
E-bit 14 
editing data buffer [117] 
EMPTY DRIVER FILE [129] 
empty file 65 
end-of-file marker 
enhanced 
addressing bit 14 
addressing modes 8 
indirect addressing 10, 13-16, 
21, 90, 31-32 
conditions for 31 
ENTERIC [138] 
entries per_block 82, 85, 92 
entry (entries) 86 
active 86 
directory 62 
FCB 538, 62 
format compatibility 91 
inactive 86 


See EOF 


points 145 

storage formats of 76 
entry_length 81, 84,92 
environment 

attributes 19 


execution 16-22 
interpreter 18-19 
SOS device driver 20-21 
SOS Kernel 19-20 
summary 22 

EOF 51,53, 63, 64-65, 68, 87, 89, 
94, 95, 96, 97, 98, [5], [19], [49] 
limit 94 
movement of 
automatic 65 
manual 65-66 
updating 65 

EOFERR [55] 

EOR 31 

error(s) [124] 
bootstrap [128] 
devicecall [125] 
file call [125] 
messages [123-130] 
numbers range 160 
reporting, SOS call 160 
SOS 
fatal [124], [126] 
general [124] 
non-fatal [124] 
utility call [126] 

event(s) 5, 104-115 
any-key 105 
arming,example 129 
arming and response 105, 108, 
125 

attention 105 
detecting an 105 
disarming 108 

existing 108 

fence 106, 109-110 
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handler(s) 5, 107, 110-111, 125 
address of 108 
examples 129 

handling 106, 107 
system status during 111 

identifier (ID) 108 

mechanism, sample 126, 129, 
139 

priority 105, 108 

processing 106 

queue 106, 108-109 
order 109 
overflow [127] 

summary of 112 

EVQOVFL [127] 
examples 

code fragments xviil 

sample programs _ xviii 

executing 

codesegments 27 
interpreter code 10 

execution 

environment 16-22 
speed 19 

ExerSOS [113-119] 

EXFN 145 

extended to bank-switched 
address conversion 34-35 
extension byte 14,31 (Seealso 

X-byte) 

extension, pointer address 154 
EXTERNAL PROCEDURE 145 
eye symbol xv 


F 
FCp 82 

entry 53,62 
FCBERR- [128] 
FCBFULL [54] 
fence [91], [93] 
fence, event 106, [91], [93] 


field(s) 
formats 89-92 
bank-pair 14 
pointer 79 
FIFO (first-in, first-out) 109 
FILBUSY [55] 
file(s) 7-8, 52 
assembly-language code [133] 
block 50-56, 62 
allocation forsparse 98 
call(s) 69-78, [2] 
errors 160, [125] 
Character 50-56, 57 
Closed 52-53 
closing before TERMINATE 
[103] 
code 145 
partofacode [135] 
control block 64 
copying sparse 98 
Creating interpreter 143 
data formats of relocatable 
assembly-language code 
146 
defined 50 
directory 57-58 
format 78-92 
relocatable 120 
Orabsolute 143 
reading 91-92 
empty 65 
entry (entries) 78, 85-89 
inactive 86, 89 
sapling 89 
seedling 89 
Subdirectory 89 
tree 89 
information 62-64 
input/output 67 
interpreter, creating an 143 
level,system 66 
managementcalls 5 
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maximum capacity ofa 94 
name(s) 58-59, 60 
illegal 59 
legal 59 
syntax 59 
open 52-53, 63 
Ooperationson 68 
organization 76-99 
code [132] 
sapling 93,95 
seedling 93,95 
SOS 56-62 
sparse 63, 94, 97-98 
standard 57-58 
locating abytein 98-99 
storage formats of 92-99 
structure 
common 3 
hierarchical 8 
ofablock 50-51 
of a character 50-51 
ofasapling 96 
ofaseedling 95 
ofatree 96 
subdirectory 5/7, 78 
system 
relationship to device 
system 5/7 
rootof 59 
SOS 55-62 
tree 61 
top-level 57 
tree 94, 96-97 
growinga 92-95 
type 68 
volume directory 77 
file count 82,85 
file name _ 60, 63, 80, 83, 87 
file type 64,87, 91, [4], [13], [18] 
FIND SEG 26,30, 121, 122, 
[77-79] 
flexible disk 42, 77, 93, [109] 


floppy disk See flexible disk 
flow of control 27 

FLUSH 66, 72, [37], [41-42] 
FNFERR [54] 

form 


bank-switched 13 
Current-bank-switched 13 
ofaSOScall 148, 160 
format(s) 
absolute or relocatable 143 
date andtime 90 
directory file 78 
of attribute table [137] 
of directory files 78 
of information onavolume 77 
of name parameter 159 
of relocatable assembly- 
language code files,data 146 
relocatable 120 
volume 77 
freememory 23 
datain 30 
obtaining 121-124 
segment allocated from 29 
free blocks [23] 
FUNC [136], [139] 
FUNCTION 145 
future versions 
compatibility with 18 
of SOS 91, 92, 93 
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general purpose communications 
(.RS232) [111] 

GET ANALOG 113, 115, 
[99-101] 

GET DEV NUM 43, 44, 45, 47, 
[65] 

GET EOF 65, 66, 68, 73, [49] 

GET FENCE 110, 114, [93] 

GET FILE INFO 68,65, 68, 70, 
152, [17-21] 
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GET LEVEL 66,69, 73, [53] 
GET MARK 66,68, 72, [45] 
GET PREFIX 70, [27] 
GET SEG_INFO 26, [83-84] 
GET SEG NUM 26, [85] 
GET TIME 90,112, 115, [97-98] 
GRAFIX [110] 
graphics 16,[{110] 

area 16 

device drivers 16 
growing atreefile 92 
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hand symbol xv 
handler 
event 5,125 
interrupt 5 
handling anevent 106, 107 
hardware 8,10 
independence 2 
interrupt 105 
header(s) 43,119 
directory 78, 79-82 
subdirectory 82-85, 89 
volume directory 79, 80, 89 
header_pointer 89 
heads 7/7 
hexadecimal (hex) xviii 
digit 12 
numbers — xvili 
hierarchical file structure 8 
hierarchical tree structure 56, 76 
high-order nibble [117] 
highest bank 11 
pair 15 
highest switchable bank 15, 18 
highest-numbered bank 23 
housekeeping functions 3 


/ 
1/0 
block 51 
buffer 50, 127 
character 51 
device-independent 67 
ERROR [129] 
implementation versus interface 
76 
warning 99 
INCOMPATIBLE INTERPRETER 
[129] 
incrementloop 124 
one-bank example of 124 
incrementing a pointer 36-37 
index block(s) 93,94, 95 
master 94 
maximum 94 
sub- 94, 96 
index block 99 
indexed mode, zero-page 29 
indexing 15 
addresses 15 
indirect 
addressing 10 
enhanced 10, 13-16, 27, 30, 
31-32 
normal 14 
operation, normal 31 
pointer(s) 154, 156, 157 
with an X-byte between $80 
and $8F 158 
with an X-byte of $00 157 
indirect-X addressing 13 
indirect-Y addressing 13 
input(s) 
analog 113 
device 40 
parameters [116] 
input/output, file 67 


interface versus implementation 
76 
warning 99 
interface,SOS 76 
intermediate form, bank-switched 
addresses as 32 
INTERP [139] 
interpreter(s) 5, 16, 118-125, 145, 
[132] 
and modules 144 
BASIC 145 
code 10 
executing 10 
command [103] 
environment 18-19 
files, creating 143 
language 118 
maximum size of 18 
memory 
placement 18 
requirements of 146 
Pascal 145 
returnto 29 
sample(s) 125-142 
listing, complete 
stand-alone 118 
structure of 119-121 
table within 29, 30 
INTERPRETER FILE NOT 
FOUND [129] 
interpreter-relative relocation 
table [139] 
interpreter’s 
stack 19,110 
zeropage 19 
interrupt(s) 5, 104-115 
conflicts between 104 
handler 5, 22, 104 
IRQ 22 
andNMI 20 
ranked in priority 104 
summary of 112 


131-142 


invalid 


address 13 
jumps 29 
regions 15, 16 
INVALID DRIVER FILE [129] 
io buffer [31] 
IOERR- [72] 
IRQ interrupts 20, 22 
is newline 67, 68, [33] 


J 
JMP 27-28, [139] 
joy mode [99] 
joy_status [100] 
joystick [99] 
JSn-B [100] 
JSn-Sw_ [100] 
JSn-X [100] 
JSn-Y [100] 
JSR 27-28 
jumps 29 
inside module 29 
invalid 29 
valid 29 
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KERNEL FILE NOT FOUND 
[130] 

key pointer 87,92 

keyboard 40 
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labels xix, 120 
local 127 
language interpreter 118 
largest possible file 94 
last mod date andtime 64, 88, 
89-90, [14], [19] 
field 89-90 
LDA 31, [139] 
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leaving ExerSOS_ [119] 
legal devicenames 42 
legal filenames 59 
length 152, [3], [11], [17], [25], 
[30], [67], [116] 
letters 42,56 
level 66, [51], [53] 
level, system file 66 
limit 23, 122, [75], [78], [83] 
LIMIT 122 
line-termination character 67 
linked list 78 
linker information [133] 
linking 
assembly-language modules 
145 
dynamic loading during 145 
lists 
required parameter 129, 
150-152 
optional parameter 152-154 
loading 
dynamic, during linking 145 
assembly-language modules 
145 
routine [134] 
loading address 120, 121 
locating a byte in a standard 
file 98 
logical 
block 77 
device 53 
byte position 98 
device(s) 40 
accessinga 41 
multiple 54 
structures 76 
logical/physical device 
correspondence 54 
loop, increment 124 
low-order nibble [117] 
LVLERR- [56] 
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machine 
abstract 2 
storing the state of the 110 
macro,SOS 126 
Makelnterp [121-122] 
management calls 
device 5 
file 5 
memory 5 
utility 5 
manager, resource 2-3 
manual movement of EOF and 
mark 66 
manuf_id 45, [70] 
manufacturer 45 
mark 51,53, 64-65, 68, 97, 98, 
[45] 
movement of, automatic 65 
movement of, manual 65-66 
marker, Current position 51 
master index block 94, 96, 97 
maximum 
number of access paths 53 
Capacity ofafile 94 
number of index blocks 94 
size of aninterpreter 18 
MCTOVFL [127] 
media, removable 53,54 
medium 42,53 
MEM2SML_ [127] 
memory 6-7,23 
access techniques 27-38 
addressing, bank-switched 
10-13 
allocation 25,121 
bookkeeper 7 
Call(s) 25-27 
errors 160 
conflict 121 
avoiding 121 


7 
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management /7 
calls 5 
obtaining free 
placement 
interpreter 18 
module 144 
SOS device driver 21 
SOS Kernel 20 
S-bank 19 
segment 7 
size, maximum 6, 10 
unswitched 28 
messages, error [123-130] 
min_version 81, 84, 88 
mode(s) 
absolute addressing 29 
addressing 10-16 
enhanced addressing 8 
newline information 67 
zero-page addressing 29 
indexed 29 
modification date andtime 68 
module(s) 5, [132] 
absolute 143 
addressing 27-29 
assembly-language 19, 118, 
143-146 
linking 145 
BASIC invokable 145 
Creating 146 
driver 41 
execution, bank-switching 
for 30 
formats 146 
loader [134] 
Pascal 145 
program ordataaccess by 145 
relocatable 143, 146, [132] 
multiple 
access paths 52 
logical devices 54 
volumes 54 


121-124 


N 
name(s) 60, 68 
device 60 
file 58-59, 60 
local 59 
parameter 159-160 
volume 55-56, 60 
name_length 80, 83, 87 
naming conventions 76 
new_pathname [9] 
NEWLINE 67, 68, 69, 71, [33-34] 
newline 
Character 6/7 
mode 6/7 
newline char 67, 68, [33] 
newline-mode information 67 
nibble 
high-order 
low-order 
NMI 114 
interrupts 20 
NMIHANG [127] 
NORESC_ [72] 
notation § xviii 
andsymbols xviii 
bank-switched address 15, 
a3 
extended address 15 
numeric xviii 
segmentaddress 23-27 
NOTBLKDEV [56] 
NOTOPEN § [72] 
NOTSOS [55] 
NOWRITE [72] 
null characters (ASCII $00) 97 


[117] 
[117] 


number(s) 
decimal xix 
device 44 


hexadecimal xiv 
reference 52 
slot 44 
changing 46 
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unit 44 
version 45 
numeric notation xviii, xix 


O 
OPEN 52, 53, 68, 69, 71, [29-32] 
call,example 128 
operating system 2-3 
defined 2 
operations 
asynchronous 5 
normal indirect 31 
ondevices 45-46 
onfiles 68 
sequential read and write 50 
opt header 120 
opt header length 120 
option list 152, [3], [11], [17], 
[29], [67] 
optional parameter list 152-154, 
[x] 
ORA 31 
order of event queue 109 
organization, code file [132] 
OUTOFMEM [56] 
output device 40 
overview of the Apple Ill 3-8 
OVRERR_ [54] 


Pp 
page(s) 23, [31], [78], [81], [83] 
part of segment address 25 


parameter(s) 
formatofaname 159 
input [116] 
list, 
optional 152-154, [x] 


required 129, 150-152, [x] 
name 159-160 
passing 145 
pointer 145 


parent_entry_length 85 
parent_entry_number 385 
parent_pointer 85 
parm_count [xi] 
parm list 149 
Pascal 118, 148, [132] 
and BASIC modules 145 
assembler 145, [134] 
interpreter 145 
prefix 62 
program 145 
versus SOS prefixes 62 
path(s) 
access 52 
information 64-66 
multiple 52 
maximum number of 56 
pathname [3], [7], [9], [11], [17], 
[25], [29] 
pathname 52, 59-61 
full 62 
partial 61-62 
syntax 60 
valid 61 
PERFORM 145 
period 42,56 
peripheral device 8, 104 
physical device 40, 54 
correspondence with logical 
devices 54 
PNFERR_- [54] 
point, decimal xix 
pointer(s) 31,69, 152 
address extension 154-159 
byte orderof 79 
comparing two 37 
direct 154, 155-156 
tocurrent 156 
to X-bank 155 
extended 123 
fields 79 
incrementing a 36-37 


indirect 154, 156-159 
manipulation 36-38 
parameters 145 
preceding-block 78 
self-relative [136], [138] 
three-byte 98 
POSNERR [55] 
prefix(es) 60, 61-62 
Pascal 62 
restrictionson 62 
SOS 62 
versus Pascal 62 
PRINTER [111] 
printers 40 
priority of zero 108 
priority-queue scheme 108 
PRIVATE [138] 

.XPROC [136], [139] 
procedure(s) [135], [136] 
attribute table [136] 

code [136] 

dictionary [135] 

entries [136] 
PROCEDURE NUMBER _ [138] 
procedure-relative relocation 
table [139] 
processing anevent 106 
Processor, Apple Ill = xvii 
Product Support Department 45 
program 

execution, restrictionson 14 
exiting from 66 
programming 
assembly-language xiii 
restrictions, circumvention of 

SOS 3 
psuedo-opcode(s) [136] 
FUNC [136] 

PRIVATE [138] 

PROC [136] 

PUBLIC [138] 
PUBLIC [138] 
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queuing anevent 106 


R 
range, X-byte 15 
READ 6/7, 68, 71, [35-36] 
read and write operations, 
sequential 50 
read-enable bit [12], [18] 
reading adirectory file 91 
ref_num 52, 64, 67, [2], [29], [33], 
[35], [37], [39], [49] 
[41], [43], [45], [47] 
references, relocation [138] 
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invalid 15,16 
risky 15,16 


release memory 25 

RELEASE SEG 27, [87] 

relocation 146 

constant [138] 
information 145 
references [138] 
table(s) [138] 
base-relative [138] 
interpreter-relative [139] 
procedure-relative [139] 
segment-relative [139] 

RELOCSEG NUMBER _ [138] 

RENAME. 69, 90, [9-10] 

req access [30] 

request count [35], [37] 

REQUEST SEG 25, 121, [75-76] 
call 30 

required parameter list 129, 
150-152, [x] 

example 129 

resource manager 2-3 
defined 2 

resources 112-114 
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restrictions 
addressing 15 
bank-switching 28 
On program execution 14 
result 69, 151 
return to interpreter 29 
risky regions 15, 16 
addresses 32 
avoiding 37 
warning 32 
ROM ERROR: PLEASE NOTIFY 
YOUR DEALER [130] 
root of filesystem 59 
S232 [111] 


S 
S-bank 11, 23, 28 
address 12, 38 
insegment notation 25 
locations, direct pointersto 155 
memory 19 
sample programs, examples xiv 
sapling file 93,95 
entry 89 
structure ofa 96 
SBC 31 
scheme, priority-queue 108 
SCP 43 


screen 40 

search mode [77] 

sectors // 

seedling file 93,95 
entry 89 


structure ofa 95 
seg address [85] 
seg id [75], [78], [83] 
seg num_ [76], [78], [81], [83], 
[85], [87] 
segment 23-24 
address 24, 38 
bank partof 25 
conversion 33-35 


notation 23-27 
page partof 25 
allocated from free memory 29 
dictionary [132], [134] 
memory 7 
of memory, allocatinga 121 
to bank-switched address 
conversion 33 
to extended address conversion 
33 
segment-relative relocation 
table [139] 
SEGNOTFND [88] 
SEGRODN [88] 
SEGTBLFULL [88] 
sequential 
access 51 
devices 7 
read and write operations 50 
serial printer (PRINTER) [111] 
SET EOF 66, 68, 72-73, [47-48] 
SET_FENCE 107, 110, 114, [91] 
SET FILE INFO 63, 68, 70, 88, 
90, 152, [11-16] 
SET LEVEL 66, 73, [51] 
SET_ MARK _ 66, 68, 72, [43-44] 
SET PREFIX 70, [25-26] 
SET_ TIME 90, 112, 115, [95-96] 
slash (/) 56,60 
slotnumber 44 
Change 46 
of zero 44 
slot_num 44, [68] 
software, common foundation 
ior 2,3 
Sophisticated Operating System 
See SOS 
SOS xvii, 3, 5-6, 16, 104 
1.1. xix, [106] 
1.2 18, 77, 81, 82, 84, 85, 88, 92. 
93, 95, 99, 105 
1.3 xix, [106] 
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call(s) 8 

block [103] 
formerror 160 
reporting 160-161 
formof 148-154, 160 
types of 148 

device 

driver 
environment 20-21 
memory placement 21 


system 43 
disk request 55 
errors 


fatal [124], [126] 
general [124] 
non-fatal [124] 
filesystem 56,58 
future versions of 91, 92,93 
implementation 76 
interface 76 
Kernel 19 
environment 19-20 
memory placement 20 
macro 126 
for SOS call block 126 
prefix(es) 62 
versus Pascal 62 
programming restrictions, 
circumvention of 3 
specifications [105-111] 
supportfor 76 
system 104 
versions xix, [106] 
SOS.DRIVER 6, 41 
SOS.INTERP 118 
SOS.KERNEL 6, 41 
sparse file(s) 63, 94, 97-98 
block allocation for 98 
copying 98 
specialsymbols xv 
STA 31 


stack 17,20 
interpreters 145 
overflow [127] 
pages 19 
stand-alone interpreter 118 
standard devicedrivers [109-111] 
standard file(s) 57-58 
locating abyte in 98-99 
storage formats of 92-99 
state of the machine, storing 
the 110 
status request 
$00, block device [60] 
$01, character device [60] 
$02, character device [61] 
status code [59] 
status list [60] 
STKOVFL [127] 
stop symbol xv 
storage formats 
directory headers 76 
entries 76 
of standard files 92-99 
storage type 64, 80, 83, 87, 89, 
92, 95, 96, 97, [5], [19] 
string buffer [117], [118] 
structure(s) 
hierarchical tree 56, 76 
logical 76 
of asapling file 96 
of aseedling file 95 
ofatreefile 96 
of aninterpreter 119-121 
of block files 50-51 
of character files 50-51 
sub type 44, 45, [69] 
subdirectory (subdirectories) 8 
file(s) 57, 78 
entry 89 
header 82, 83, 89 
subindex block 94, 96 
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summary 
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of interrupts andevents 112 
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highest 15, 18 
symbol(s) 

eye xix 

hand xix 

stop xix 

v1.2 xix 
syntax 

devicename 42 

filename 59 

pathname 60 

volume name 56 
System Configuration Program 
(SCP) 41,46 
system 

clock 112 
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file level 66 

operating 2-3 

Status during event handling 111 
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table 
procedure attribute [136] 
within interpreter 29, 30 
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TERMINATE 114, 115, 126, 131, 
[xi], [103] 
call, coding 131 
closing files before 
termination character 
[64] 
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pointer 98 
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time 
date and 
creation 64, 81, 84, 88, 89-90 
format 90 
last mod 64, 88, 89-90, [14], 
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time pointer [95], [97] 
time-dependent code 104 
timing loop 19, 104 
TOO MANY BLOCK DEVICES 
[130] 
TOO MANY DEVICES [130] 
TOOLONG [128] 


top-level files 57 
total_blocks 45, 82, [23], [70] 
tracks 77 
transfer control 28 
transfer_count [36] 
tree file 94, 96-97 
entry 89 
growinga 92-95 
structure ofa 96 
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